I’ve blogged before that I think the way a developer names blocks of their code says a lot about their experience, not only in a particular platform, but also what they know about the Software Development Life Cycle. But I don’t want to rehash that. Today, I want to talk about when and why to comment. When I create a new class definition, I typically try to add a summary comment right then. I also expect this of my team members. It may seem pedantic, but there’s a very good reason for it. Expressing in English* the intent of the class tends to help me clarify the Single Responsibility that I have for that class. If I find that I have trouble specifying the expected behavior of a class in the summary, that generally means I don’t have the plan for why/how/when I need to use that class. If I find I need a paragraph to explain the purpose of the class, it might be doing too much.
Doing too much is bad.
So, when I find that this is the case, I look to see which parts of the summary should be broken out — those breakouts typically fall along class definition lines, and before I know it, I can summarize most classes in one or two sentences, and the only do as much as they should.
Only doing as much as you should is “A Good Thing.(tm)”
The other benefit is that my colleagues can take a look at my code and understand large blocks without digging though and inspecting each member of the class. Truly, that was the point of OOP. Rather than trying to explain how each block of code works (inline comments), explain why each block of code exists (first-class documentation). This rule of thumb works the same for members of a class. If you can type out a sentence explaining what you’re trying to do, there’s a much better chance that you will actually do that thing. There’s even a good chance that you’ll be able to identify things that are leaking in and shouldn’t be. If When your code has gotchas, these should be outlined in the block, or the blocks. This is your chance to explain yourself. Do you need that string to be formatted just so? Do you return something in a particular order? What do you expect from consumers? While I’m on this subject, please don’t just fill out comments to make the compiler warnings go away. That’s just a waste of your time.. I am aware of a particular tool that provides phantom summaries; summaries that are there, but have no substance. The intentions were good, but it entirely misses the point. Imagine you bought a dictionary and all of the definitions used the word in the definition.
Definition: A sentence that defines something.
C# and Java both have great documentation support, I believe that other languages/platforms have started to make these summary-type comment sections closer to “first-class citizens,” so your reasons for not commenting code is dwindling. I’ll leave you with this: Every line of code makes perfect sense while you’re writing it. Really good code will make sense to other people with a little bit of explanation. Great code is that which can be understood by your future self, and the people that follow you. Why not hedge your bets and provide some good documentation to make your good code, great code. * It doesn’t have to be English, the first language of your team is best for these comments.