Righteous Naming

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

Good names take effort[1]. Bad names, eventually, take more effort. Good names help code look like (awkward) prose[3] 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[4]

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    

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

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

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

Also published as Rightous Naming on Medium

 
0
Kudos
 
0
Kudos

Now read this

Don’t Mock It: Hack It

Python holds a deep, dark secret: it can be as unpredictable as Ruby if we let it. Even with the new typing1, the staggering flexibility of Python at runtime remains. We can change individual instances of classes to anything we want, and... Continue →