2nd hardest thing in computer science

A presentation at PHPCon PL 2019 in November 2019 in Szczyrk, Poland by Paweł Lewtak

“There are only two hard things in Computer Science: cache invalidation and naming things.” Phil Carton

*things variables methods classes modules comments inline docs commit messages

“Don’t code, write prose” Sławomir Sobótka

“Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.” Donald E. Knuth

function a($b) { sort($b); $c = count($b); if ($c % 2 === 1) { return $b[($c - 1) / 2]; } else { return ($b[$c/2 - 1] + $b[$c/2]) / 2; } }

function median($pool) { sort($pool); $size = count($pool); if ($size % 2 === 1) { return $pool[($size - 1] / 2]; } else { return ($pool[$size/2 - 1] + $pool[$size/2]) / 2; } }

Programming is mapping from problem domain via intermediate domain into programming domain

$total = $price * $qty; $total2 = $total - $discount; $total2 += $total * $taxrate; $total3 = $purchase_order_value + $available_credit; if ($total2 < $total3) { echo “You can’t afford this order.”; }

$order_total = $price * $qty $payable_total = $order_total - $discount $payable_total += $payable_total * $taxrate $available_funds = $purchase_order_value + $availble_credit if ($payable_total < $available_funds) { echo “You can’t afford this order.”; }

“No-one sets out to write legacy code” Rachel Willmer

Misapplied Java design patterns are the root of all AbstractWordFactoryFactory(“evil”) anonymous HN comment

Naming conventions CamelCaseClass methodName someVariable CAPITAL_CONSTANT

Bad name Does more that what is says Says more than what it does Does the opposite Contains more than what it says Says more than what it contains Contains the opposite

Alternatives fetch find lookup create calculate

is_active() function is_active() { if (cond) { return ‘false’; } return ‘true’; }

is_valid() function is_valid() { if (input_is_valid) { return true; } }

Plural / singular names function get_person() { return array(‘John Doe’, ‘Jane Doe’); } function get_employers() { return ‘John Doe’; }

/** * Actually it returns the highest price. */ function get_lowest_price($user) { }

/** * Actually it returns the highest price. */ function get_lowest_price($user) { if ($user === null) { return _get_highest_price(); } else { return _get_lowest_price($user); } }

<ThatThing>Manager UserManager StringManager ProductManager etc.

Alternatives Builder Writer Adapter Factory Handler Provider Converter

$client = new GuzzleHttp\Client(); $url = ‘https://2019.phpcon.pl/’; $response = $client->request(‘GET’, $url); $response_code = $response->getStatusCode(); if ($response_code === 200) { echo ‘It works!’; } elseif ($response_code === 418) { // ??? }

$client = new GuzzleHttp\Client(); $url = ‘https://2019.phpcon.pl/’; $response = $client->request(‘GET’, $url); $response_code = $response->getStatusCode(); if ($response_code === StatusCode::OK) { echo ‘Website works!’; } elseif ($response_code === StatusCode::IM_A_TEAPOT) { echo ‘Would like a cup of tea?’; }

Useless comments /** * Returns the data. */ function get_data() {} /** * Return maximum ID value from the database. */ function get_max_id_from_db() {}

“Code should have comments, but if your file is more than 25% comments, that’s a red flag: you may be explaining bad code” Adam Culp

Good commit message Speeds up review process Helps write release notes Helps future maintainers

Short (50 chars or less) summary of changes More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together. Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary here

Code reviews Short, bite size, single logical change

Research papers https://www.cqse.eu/publications/2005-concise-and-consistent-naming.pdf http://www.cs.loyola.edu/~lawrie/papers/lawrieJese07.pdf https://www.researchgate.net/publication/224079441_Relating_Identifier_Naming_Flaws_a http://www.veneraarnaoudova.com/wp-content/uploads/2014/10/2014-EMSE-Arnaodova-e

Paweł Lewtak
@pawel-lewtak

1 / 86

Have you heard about the two hardest things in computer science? It’s cache invalidation and naming things. I want to focus on the second one.

Let’s see common examples of both good and bad naming. What’s the common part of each of them? What’s makes names good? Can we settle on good enough or should we aim for perfect names? I’ll show some of best and bad practices so you’ll be able to recognize both of them when you make code review for your peers. Naming is one of two hardest things in CS, so I don’t claim to be right about everything but I’m open to discussion and happy to learn from you as well.

2nd hardest thing in computer science

Link for this presentation:

HTML code for embedding:

Share on social media: