People confuse the notion of naming code artifacts appropriately with documentation. While both enhance and enable the readability and comprehension of code, they serve different purposes. At least when done properly…
Pretty much every place I’ve worked has had a coding standard, and most of these have had a couple standards along the lines of:
- Thou shalt use meaningful names for variables, members, classes, files, etc.
- Thou shalt not use one-letter variable names like i because thy code will look like math…
(Many of the standards also encourage using absurdly long names in the service of “clarity”. Just as an aside, I’d like to note that clarity is often enhanced by brevity more than verbosity…)
The first one is a good rule — it only makes sense to use meaningful names rather than nonsense names. I once worked with a guy who used German variable names; meaningful for him, not so much for anyone else. The second one is not as defensible in my mind, but now I stray from my point.
My point being: Good names are crucial to the readability and comprehension of code, but they are not documentation. Names are essentially labels. They are important, but they don’t explain anything about the thing they label. That is the role of documentation.
- Why is the programming construct or artifact needed at all?
- What are its preconditions for use?
- What non-obvious effects, if any, does it have?
- What other artifacts (classes, members) are used in conjunction with it? (Remember, nothing in a program stands alone unless it is dead code…)
- What are its most common use cases? This is particularly important at higher-granularity artifacts such as classes…
- What are the valid ranges of its input and output?
- How are null pointers or references interpreted?
This is all important information that should be provided by documentation. And, typically, there is too much of it to reside comfortably in a usable name or label.
(And while we’re at it, I should also mention that requiring a colleague to read and decipher an implementation rather than just telling them in plain language what they need to know is not acceptable. Yes, competent programmers could read your code, but only with a much higher degree of effort. When you don’t provide good documentation you are saving yourself the cost of a one-time effort, but incurring multiple costs for all readers of your code.)
Both good naming and documentation are essential, but they are not interchangeable. Make your names meaningful, use the programming language syntax to express semantics where you can, but then use natural language documentation to fill in all the gaps.