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.
E.g.
1 2 3 4 5 6 7 8 9 | // make an empty list// iterate through each item in the input// if the item is over the threshold// then add to the list// return the list of items over the threshold |
What you could then do is fill in the lines of code between the comments and you’d have the perfect, commented function.
Right?
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.
Published on Java Code Geeks with permission by Ashley Frieze, partner at our JCG program. See the original article here: Talking Around Your Docs Opinions expressed by Java Code Geeks contributors are their own. |
Sometimes it’s a requirement to write “boilerplate comments.” I’m looking at you, JavaDocs for simple getters and setters.
The question to ask is what’s the benefit of JavaDoc on a getter? It’s clearly not to document the fact that it’s a getter. In a non-trivial codebase, there will be many fields/properties of objects whose purpose isn’t perfectly guessable. For example
namemight mean first name, full name, last name, alias… Fields probably need documenting somewhere. One of the best places to document a field is on one of it’s getter/setter methods, as there’s a chance that that documentation will be spotted as someone navigates the codebase.But if it just says
Gets the namethen it’s pointless! :)