Righteous Naming

> If names are not correct, language will not be in accordance with the truth of things — Confucius (attributed)

Good names take effort[¹]. Bad names, eventually, take more effort. Good names help code look like (awkward) prose[²] instead of mathematical formulas. Good names help readers focus on *what* the code is getting done rather than “WtF is this coding doing‽”. Good names reduce the need for comments or the readers to drill into the functions’ code[³]

Think of a big pile of tools, materials, and supplies. To find anything, one has to dig through, on average, half the pile. It’s like one big function or script

Think of the same stuff in unlabeled drawers and boxes. One looks through boxes unnecessarily because the contents are not obvious from the boxes’ labels (or one does not understand or does not trust the labels)

Think of the same stuff in labeled boxes grouped by some cognitive theme: material type; power source; scale of operation; etc. Not only can one know what is in a box without looking inside, one knows on which shelf or against which wall has the sort of boxes one wants. This is what well-named functions provide

Finally, using smaller drawers and boxes reduces the amount of stuff one looks through *within* the drawer or box, and smaller functions might be useful in more places because they fit in smaller spaces

Name variables, fields, attributes, accessors, mutators, packages, and files so they describe what they *are*; name functions and methods so they describe what they *accomplish*, not how they accomplish it;

filtered_items = remove_backordered_items(items)
items_after_discount = discount_bulk_orders(filtered_items)
items_by_ship_date = group_by_ship_date(items_after_discount)
return items_by_ship_date

Originally posted here

[¹]: There are only two hard things in Computer Science: cache invalidation and naming things. — Phil Karlton

[²]: Good code reads like well-written prose — Grady Booch

[³]: as long as the function is mindful and does one thing