We don’t write comments. The code is self documenting.
The people who say that they don’t write comments are 95% of the time NOT writing self-documenting code. They’re digging a hole into which someone will fall soon.
How I was taught to comment as I go
I was taught that you must write a method by first explaining what it will do in a sort of pseudocode called PDL – program descriptive language.
What you could then do is fill in the lines of code between the comments and you’d have the perfect, commented function.
NEVER DO THIS!!!
This is not commenting your code. This is writing your code twice, once in a language the computer doesn’t understand and nor does the reader.
So Code Is Just Self Explanatory..?
A lot of code should be written to explain itself, but it will largely explain what it is doing and how, it can’t really explain why.
The objective of writing documentation in code is:
- Help the reader navigate this region of the codebase
- Understand the semantics of interfaces and data
- Justify any unexpected decisions
The more self-explanatory the code is, the less you need to document, though I’d still argue in favour of things like JavaDoc, which can be published alongside the bits of your code that developers use across modules, or teams.
The important bits of this are:
- the class header – the CRC card, showing what the class is for and its major collaborators
- public API functions – what you expect people to use
Occasionally, you might write a mini user guide in the docs. For very public APIs, e.g. the Mockito library, this is a friendly thing to do. If it’s going to be something useful that everyone needs to refer to… otherwise, it may be a waste of time.
How People Get It Wrong
Here are some things that are either valueless, or counterproductive that I’ve seen in documentation:
- Commenting the obvious – we can read code and if the code is unreadable, then invest time in making it readable
- Writing stuff that nobody’s going to read – boilerplate comments, who cares?
- Saying the type/sort of things, but not why – I know it’s a string, but what does it store?
- Describing the algorithm in detail when it could be made self-evident in code
- Blether/filler – “This method is the method that is the method” – we can see in context that the thing being described is a method/function/class/variable – assume the reader wants to get to the meat of the sentence.
- Writing as though a book report, rather than for the built docs – it’s not an essay, it’s code. Your documentation may get compiled into HTML and published. So what’s the minimum we need to know.
- Not using the rich documentation features – if the documentation standard provides automatic links and cross references, then use the markup to express them, rather than miss out, or do it the long way
- Repeating yourself by saying stuff prematurely – edit the documentation as much as the code. Sometimes documentation gets a bit unstructured and ends up getting longer as a result. Clean it!
- Typos/grammar – dno’t meak me reed unspelchcked rbubish!
- Meaningless adherence to a documentation standard that demands the above – if the standard’s wrong, then change it! I’m looking at you Google Checkstyle config!
All of the mistakes can be down to writing to appease the gods, rather than help the reader. If you think about what’s missing from the file after your beautifully expressed code, and add that as a context to the future reader, you won’t write anything unnecessary and you WILL write things that are useful.