- \n
- Naming can be improved quickly. You can make a quick fix that updates some names in the code, manually or by using a tool (such as the popular clang-tidy<\/a> for example), and if your code builds, you’re nearly certain it will pass the tests.<\/li>\n<\/ul>\n
Because it\u2019s so important, I\u2019m going to provide you with guidelines on how to choose good names. I’ve taken some of these guidelines from Steve McConnell\u2019s reference book, Code Complete<\/a><\/em> (which is part of the must-reads John advises in his post \u201cHow to Get Started in Software Development<\/a>\u201d).<\/p>\n
Some of the tips come from discussions, suggestions, and code reviews I\u2019ve had with my peers at work. A couple of them I’ve worked out on my own by experimenting with code over the years.<\/p>\n
We’ll start by explaining how to avoid bad names and then focus on how to pick good ones.<\/p>\n
Don’t Use Anything Illegal<\/h2>\n
![\"\"](\"https:\/\/simpleprogrammer.com\/wp-content\/uploads\/2017\/02\/Untitled-1-2-1-1024x576.png\")
<\/p>\nLet’s get this out of the way: there are names that you are just not allowed to use in a given language.<\/p>\n
Besides using names reserved by the standard (like \u2018int\u2019), which will halt compilation, each language has its specific rules for legal names. For example in C++, some combinations of underscores (_) in a name will compile while not being legal, because they are reserved for the compiler or standard library implementer. Using them may conflict with objects or routines declared by them, leading to subtle bugs and unexpected behaviour.<\/p>\n
Here are the names that are reserved for the compiler and standard library implementers in C++:<\/p>\n
- \n
- Any name with two consecutive underscores in it (__)<\/li>\n<\/ul>\n
- \n
- Any name starting with one underscore immediately followed by a capital letter (_isOk, isOk_too, _IsNotOk)<\/li>\n<\/ul>\n
- \n
- A name starting with one underscore and in global namespace<\/li>\n<\/ul>\n
So don’t consider using such names, as they could get you into trouble.<\/p>\n
Don’t Waste Information<\/h2>\n
When you think about it, your code perfectly knows what it is doing. In fact, it is the one that knows best: it executes what\u2019s in it as faithfully as it possibly can!<\/p>\n
Giving good names is really about retaining as much of the information that the code holds as you can. Said differently, it is about not wasting information by obfuscating the code. It\u2019s interesting to note that hiding information is often encouraged, via encapsulation. But in this context it is rather information disclosure <\/em>that you want to aim for.<\/p>\n
For this reason, limit the use of abbreviations.<\/strong> Abbreviations and acronyms are convenient to write but difficult to read. As the saying goes, code is written once but read many times.<\/p>\n
However, you don’t have to systematically spell out all<\/em> acronyms to make code clearer, and some repeated unabbreviated code can even harm readability.<\/p>\n
For instance, it seems reasonable to use “VAT” in your code instead of writing \u00a0valueAddedTax every time you use it, because everyone knows what VAT is.<\/p>\n
How do you choose whether or not to use an acronym in code? Rule of thumb: if the end user<\/em> of your application would understand a particular abbreviation or acronym, then it is OK to use it in code because it shows that everyone in your domain area knows what it means.<\/p>\n
Moreover, don’t try to optimize for the minimum number of characters<\/strong>. On forums, you can see guys that argue that their method is superior because it involves less typing. But which is more of a hassle: a couple of keystrokes, or a couple of minutes staring at code, trying to figure it out?<\/p>\n
You certainly don\u2019t want to waste time figuring out what a function and method name meant, especially when you can make their names as long as necessary. Research from the University of Southampton (Rees 1982)<\/a> suggests that function and method names can reasonably go up to 35 characters, which sounds like a lot, but a longer name can help you understand what a piece of code is and what it does with only a quick glance.<\/p>\n
However, the length of a function name can also become bloated for bad reasons:<\/p>\n
- \n
- If a function\u2019s name is too long because the function is doing too many things<\/strong>, the fix is not in the naming, but at the function level itself by breaking it down into several logical parts.<\/li>\n
- Function names get artificially bloated when they include superfluous information that is already expressed by their parameter types<\/strong>. For instance:<\/li>\n<\/ul>\n
- If a function\u2019s name is too long because the function is doing too many things<\/strong>, the fix is not in the naming, but at the function level itself by breaking it down into several logical parts.<\/li>\n
- A name starting with one underscore and in global namespace<\/li>\n<\/ul>\n
- Any name starting with one underscore immediately followed by a capital letter (_isOk, isOk_too, _IsNotOk)<\/li>\n<\/ul>\n
- Any name with two consecutive underscores in it (__)<\/li>\n<\/ul>\n