Names

*Disclosure: This post may contain affiliate links, meaning, at no cost to you I may get some coffee money if you click through and make a purchase.

My posts up to now have been some general introduction the Software Development and I wanted to continue that trend (and do so for a while longer). This time I thought we’d take a look at something I think is very important, Names.

As Software developers we name a lot of things; methods, functions, data members, properties, variables, arguments, packages, and of course classes. One thing I have aimed to do since reading ‘Clean Code’ by Robert Martin (also known as Uncle Bob), is to give EVERYTHING I name decent intention-revealing names. That is, I try to name things in such a way that anyone (including myself) who reads this code can have a clue what my intention was when I originally wrote it.

One of the main goals of intention-revealing names is it should result in an almost comment free code base, granted you will have some comments in there (and as I like to try to use the StyleCop style guide for Visual Studio I don’t fully adhere to this rule myself). Lets check out an example to see what I mean.

Lets say you’re reviewing code trying to find a bug (the code is what you wrote 6 months ago) and you come across this.

int T; // time

It is not unreasonable to think, what is time, time since when, why is this time important and why is it named T? In reality if it had just been given a more intention-revealing name there wouldn’t be the need for the reader to go hunting what it is and what it’s for. Instead it could be

int TimeSincePlayerLastMadeMove;

The above code gives far more information that ‘T’, (although if I’m honest I’d say we’d want to go one step further and apply the Single-Responsibility Principle and wrap this up in a class, but I’ll go over that in more details in another post).

We also want to avoid adding unnecessary information that just added to the confusion, so for example if we started off with

List<GamePiece> PieceList; // Players Game Pieces

We’ve included the collection type in the name but what if we change it from a list to something else, say an ICollection? Whilst the name infers its a collection of some sort any future user may well try to make use of it as if it were a list, as mentioned leading to confusion. Instead we could use

List<GamePiece> GamePieces;

An obvious issue Uncle Bob raised was that we should make meaningful distinctions within our code and not just code to make the compiler happy and we should avoid what he calls ‘noise’ words like, a, an, and the, that again may add confusion where there just isn’t any need to have it.

The book explains that we should strive to use pronounceable names, things that when we are in a meeting people know what it is we are talking about. Unfortunately I don’t have a personal example of this (though I would say acronyms are one of my biggest pet peeves in meetings), however he does have one he explains that he had come across ‘genymdhms’ which stood for ‘generation date, year, month, day, hour, minute, and second), not ideal really.

I won’t run through the entire section from the book there’s just a few more points I’d like to mention.

Class and method names, now class names should be a noun such as Customer or Account, they are names of things and so we should be using naming words. Method names should be a verb such as DeleteAccount, GetUserName, or SaveGame, they are things that do something so we should be using doing words. We’re very lucky today that if we name something and decide it’s not the right name we can quite easily refactor our code and have a name change ripple throughout the code base.

A key point that I think Uncle Bob raises that is spot on is the reason people use shorter less meaningful names is to ensure it shortens the code for that line or it means the required coding standard. Two of the coding standards I’ve come across in the past was MISRA and Google C++ Style, and they have a line length limit. I can’t recall the MISRA length I think it was between 80 and 95 lines but the Google Style limit was 80 with additional rules when 120 and 150 was broken (though in all honesty I think 150 is a bit much). The main reason for both of these limits was a throwback to when screen sizes were limited and if code was going to be printed. Now for the printed code issue I have not and I don’t know anyone who has had to print code out (at least in the past few years). For the former as our monitors are continuously progressing this just seems like a poor reason and I can’t see how it will continue as a rule. Though to be fair Google themselves state it is a throwback to the 1960s (link here).

So there we go, one of our many aims of writing code should be to make the things we name far less confusing than they need to be. Granted I am cherry picking things here and I do highly recommend any and every one interested in writing software pick up Uncle Bobs book and give it a read.

Leave a Reply

Your email address will not be published. Required fields are marked *