Code Documentation for me, and as I expect for many others, a topic that their opinions vary greatly over the course of their careers. I’m fairly certain that most people follow the same pattern:
- Education – Told to document in assignments, hated it and feel that its more pain than its worth.
- Junior Programmer – Documents everything sometimes redundantly. Documentation is the doorway to advancement.
- Mid-Level Programmer – Documents everything but not so redundant. Understands giving coworkers explaination.
- Senior Programmer – Documents rarely, and only what absolutely needs it.
When development is busy, deadlines are looming, the first sacrificial lamb is documentation. Why fight this? It’s the way it is and the way it will always be. “Self Documenting Code” is a buzzword that gained popularity with Java, but could possibly be more than just a buzzword if done correctly. It’s a matter of understanding when the code is enough, when to write documentation and understand the pros/cons of any single line of comments.
Pros
Informs the user of the intent of the Class - Intent is the most important word there. If you are just rewriting the code in English, you are helping no one. The intent of a class should never change throughout its lifetime, the implementation changes often. If you are documenting the implementation, not only are you having to change the code, you have to update the documentation. And, this is one area where most programmers fail, allowing stale comments to persist in code. Notice that I mention only Class. Methods should be named well enough that it is obvious what they do.
What about tricky areas of code? If a piece of code is so clever in its implementation, you did it wrong. Rather than spending time commenting that bit of code, think about cleaner ways of writing it. Once you have the implementation down to an obvious state, you don’t need documentation and your code is better for it. Exception: If after reducing the complexity of the code, you still want to explain elements (say, explain what a third-party API is doing) that is fine.
What about commenting complex Methods? If the name of the Method does not explain everything the method does, you need to refactor to simplify the method, possibly breaking it into multiple simple methods. Exception: If a method made it past this point and is in public use, it’s much more difficult to refactor. Document it and learn from this mistake.
Cons
Context switching. Similar to bilingual speakers, switching from (say) Spanish to English and back to Spanish takes mental overhead. The same is true with code and comments. When a developer is reading code, the truly are reading it. They are parsing syntax of the particular language, switching to reading comments has a cost associated with it. When those comments don’t add anything to the understanding of the code, it is expensive for little reward.
So, generally, I find myself caring less and less about people fully commenting code, and more and more about writing clean well structured code that can be easily understood. I do like to see general intent comments about the Class itself, but more than that it typically not needed.
APIs
Notice that I like to use the words “generally” and “typically”. This gives me nice outs when people raise all the legitimate situations where fully documenting code is beneficial. Perhaps the biggest reason to fully document code is when writing an API. Especially if you are generating API Docs via JavaDoc, Doxygen, etc. Unfortunately, this situation necessitates writing fully comments even where the vast majority are redundant. The morale of the story is don’t write APIs… if it was only that easy.
