Comments on: How to choose good names in your code

By: Amir Shrestha

Amir Shrestha — Tue, 08 Aug 2017 22:06:00 +0000

Consistency in coding style is good… However, this is very challenging to achieve in practice because we may have many third party libraries that follows its own coding guidelines, and your company may have its own guideline…
There is always a debate on how to name your class member variable…
m_data or _data or data_ ?
Another example is, C++ standard library uses vector as a class name, Qt library uses QVector …

It would be great if we have a uniform naming convention across all projects…

And the C++ coding guidelines says in NL.8: Use a consistent naming style

There are many styles and when you use multiple libraries, you can’t follow all their different conventions. Choose a “house style”, but leave “imported” libraries with their original style.

By: Dan Gendreau

Dan Gendreau — Sat, 04 Feb 2017 01:11:00 +0000

One technique that helps me to find the best names for function parameters is to write a quick Doxygen comment before writing the function signature. By writing the function’s Doxygen brief in simplest terms, the parameter names will emerge naturally and the resulting implementation usually reads more fluently. e.g.

/// Insert a p note with the specified p velocity into the note p stack in sorted order.
void NsInsertSorted( NoteStack* stack, uint8_t note, uint8_t velocity );

By: triangle_soup {neil}

triangle_soup {neil} — Thu, 02 Feb 2017 23:44:00 +0000

I would also suggest that it’s important to remove ambiguity and avoid the use of prefix verbs such as compute or calculate for function names, which are largely meaningless since everything is computed or calculated, especially when you use auto; e.g.

computeEmployeeSalaries (); // Looks like intention is to call an “update” function.
const auto result = computeEmployeeSalaries(); // Looks like result holds the call status. Wrong.

Remove ‘compute’ and things start to look a lot different; e.g.

getEmployeeSalaries ();
const auto result = getEmployeeSalaries();
const auto result = employeeSalaries ();

Edit:
Once the ‘compute’ prefix has been removed, ‘result’ looks inappropriate, which is a good thing and my intention with this example. It’s a poor variable name, after all.

By: Jonathan Boccara

Jonathan Boccara — Thu, 02 Feb 2017 17:43:00 +0000

In reply to Bartlomiej Filipek. By now we've realised the importance of good naming, so in the new code we add or refactor, we really do our best to use good names everywhere, so 90% I would say. But in old code it really varies!

By: Jonathan Boccara

Jonathan Boccara — Thu, 02 Feb 2017 17:43:00 +0000

In reply to Jörg. thanks for sharing your experience Jörg.

By: Jörg

Jörg — Wed, 01 Feb 2017 18:43:00 +0000

I would like to add another point: If your variable has units, spell them out! Ages are usually given in years, so it’s fine to leave it at that. But you should always write speed_m_s to save the next person from searching for any hint whether it may be km/h or mi/h.
I have found several bugs in code reviews just by fixing this!

By: Bartlomiej Filipek

Bartlomiej Filipek — Tue, 31 Jan 2017 07:27:00 +0000

Thanks for a great article.

I am glad that you mentioned negations. It’s best to avoid them! It’s especially confusing if you have a name that has a negation (like “IsNotValid”) and you try to use it in a bit more complicated condition. So ‘stay positive’ is a good advice here 😀

What’s your experience when it comes to actual code bases… are/were your projects using proper names all the time? 50% of cases? 20%?
From what I’ve seen it could be around 50…60%.