ruk·si

📛 Naming

Updated at 2015-05-26 15:08

Let the meaning choose the word.
Not the word to be coming the meaning.

Improve your vocabulary. Becoming a better writer allows you to write better code. Read books with puns like Terry Pratchett, noticing puns allows you to spot words with double meaning, so you can avoid them.

Prefer short names over long names.

// bad
company_person_collection
// good
staff

Avoid syntactical and design pattern names. You might be used to seeing this kind of code in examples. They are usually unnecessary bloat or more useful alternatives exist.

// bad
AbstractConfigurationFactory
variable
data
InvoiceManager => InvoiceBuilder, Invoicer
TaskManager    => TaskPlanner, TaskSupervisor, TaskMaster, Tasker

Avoid jargon when an understandable English equivalent is available. Be especially careful when bringing paradigms from other languages.

// bad
ShipmentMonad
// good
Shipment

Remove redundancy.

// bad
AbstractObjectEntityClientDataContainer
// good
Client

Use strange names if the alternative is too generic. Making up a understandable word is better than using a word that is too generic.

// bad if it's a specific kind of container
Container => Bucket, Bag, Box, Holder, Vessel, etc.

// but note that if we are talking specifically
// about e.g. Docker containers, then Container is the best

Then you can talk about "vessels" and those familiar with the code understand what you mean, and you don't need to explain further.

This does "reserve" the word in that context so be careful with it and remember to reuse the strange word in similar use-cases.

Multiple words can be replaced by more specific words.

// worst => best
PlanEvents       => EventPlanner / Schedule
appointment_list => calendar
company_person   => employee / owner
ReallyFast       => Quick

Prefer common conventions of the language and community. And break those conventions intentionally.

`get_*()` returns the variable 
    => use `fetch`, `find`, etc. for more advanced variants of `get`

In C++ and Golang, variables are frequently shortened a lot e.g.,
* `id` is usually `identifier`
* `i` is usually `iterator` or `index`
* etc., don't fight it, just go with it

Stop and plan a little ahead. If you don't know what a thing should be called, you don't fully know what it represents and can't write proper code for it. Remember to return and rename it before making the pull request.

Don't hesitate to rename. Rename is the most productive refactoring tool.

Sources