Writing code that speaks

Writing code that speaks

Code is read many more times than it is written. In this talk I'm going to walk through simple, practical examples of how you can give your code a voice. We're going to explore the power of word choice, and how you can develop naming habits that lead to beneficial refactorings.

D20a680b224928e9743c966ebb06d3ce?s=128

Caleb Porzio

June 16, 2017
Tweet

Transcript

  1. 1.
  2. 3.
  3. 5.
  4. 6.
  5. 7.

    "Any fool can write code that a computer can understand.

    Good programmers write code that humans can understand." Martin Fowler
  6. 8.

    "Indeed, the ratio of time spent reading versus writing is

    well over 10 to 1. We are constantly reading old code as part of the effort to write new code. ... [Therefore,] making it easy to read makes it easier to write." Uncle Bob (Robert C Martin)
  7. 10.

    1. Avoid meaningless words 2. Strive for consistency 3. Don't

    make my brain hurt 4. Name according to scope 5. Don't make me look things up 6. Leverage metaphors
  8. 17.

    ! The more abstracted your code is, the more abstract

    your words will be (1. Avoid meaningless words)
  9. 22.

    Hungarian notation ! $aNames = ['bob', 'carol', 'jim']; $sName =

    'jack'; $iAge = 23; (1. Avoid meaningless words)
  10. 23.

    Hungarian notation ! $names = ['bob', 'carol', 'jim']; $name =

    'jack'; $age = 23; (1. Avoid meaningless words)
  11. 30.

    Pick a word and stick with it echo $blog->body; echo

    $comment->text; echo $testimonial->content; (2. Strive for consistency)
  12. 31.

    Pick a word and stick with it echo $blog->body; echo

    $comment->body; echo $testimonial->body; (2. Strive for consistency)
  13. 34.

    Pick a word and stick with it service.api_key service.key service.public_key

    service.secret_key service.api_secret service.api_public service.secret ... (2. Strive for consistency)
  14. 37.

    Abbreviations I'm ok with ! auth authentication // TODO admin

    administrator id identifier db database i iteration int, bool integer / boolean e, z exception / zonda (3. Don't make my brain hurt)
  15. 38.

    Abbreviations I'm NOT ok with ! addr address attr attribute

    err error arr array opt option msg message img image (3. Don't make my brain hurt)
  16. 49.
  17. 50.

    1. Avoid meaningless words 2. Strive for consistency 3. Don't

    make my brain hurt 4. Name according to scope
  18. 51.

    Compound method names class Cart { public function addProduct() {};

    public function removeProduct() {}; public function changeProduct() {}; } $cart->addProduct(); (4. Name according to scope)
  19. 52.

    Compound method names class Cart { public products; } class

    Products { public function add() {}; public function remove() {}; public function change() {}; } $cart->products->add($product); (4. Name according to scope)
  20. 53.
  21. 56.

    1. Avoid meaningless words 2. Strive for consistency 3. Don't

    make my brain hurt 4. Name according to scope 5. Don't make me look things up
  22. 66.

    Bare integer class HttpStatus { const CREATED = 201; }

    $response = $request->post('/users', $payload); $this->assertEquals(HttpStatus::CREATED, $response->statusCode()); (5. Don't make me look things up)
  23. 69.

    Implicit method name Post::getFirst(); // creates a new post if

    can't find one (5. Don't make me look things up)
  24. 71.

    1. Avoid meaningless words 2. Strive for consistency 3. Don't

    make my brain hurt 4. Name according to scope 5. Don't make me look things up 6. Leverage metaphors
  25. 72.
  26. 73.

    "This transfer of some quality of the known to the

    unknown is like a beam of light; we "see" (that is, we understand) something about the unknown in the light of the known." Mary Oliver (A Poetry Handbook)
  27. 79.

    1. Avoid meaningless words 2. Strive for consistency 3. Don't

    make my brain hurt 4. Name according to scope 5. Don't make me look things up 6. Leverage metaphors
  28. 83.