How to comment your source code? This topic comes up every once in a while, and sometimes it leads to heated discussions. The consensus is something like “comment why, and not how”. Useful as it seems, I think it is important to give examples from real-world scenarios. So, let’s look at such a case.
I’ve been working on the integration between Hadoop and HGST Active Archive S3 Object Storage product recently, and while dealing with the internals of the S3A File System that we are improving at the company, as well its interaction with YARN, I’ve come across an interesting piece of code in the Hadoop code base. Before going into its details, look at it without any comments:
If we ignore the method name and signature, the implementation is only 4 lines of code, and it almost reads like a piece of text in English. It is not even very wide, and does not seem verbose at all. Without knowing anything about Hadoop at all, even with a very very superficial knowledge of Java, a junior programmer can look at the code, and have a general idea of the flow.
Now, let’s look at the real code:
10 lines of explanation for a seemingly straightforward piece of code that is only 4 lines. First of all, the comment section start by motivating and justifying its existence by warning that the small piece of code is a little weird, but it is required. Then it goes on to give as much context as possible. It explains in very clear terms the why of the code (the how of the code is already clear) and potential pitfalls it defends against.
Keep in mind that the Hadoop code base is being developed for the last 10 years, it is more than 1.7 million lines of code (and growing), more than 800 people contributed to it, and it has more than 25 components. Keeping the complexity manageable from the highest level down to the source code quality and commenting level becomes really important in this case.
Next time you’re thinking about writing a code comment for a few lines of code, come back to this striking example, and think about it again. No matter how different your project might be, being a good citizen in the world you live will pay off, maybe not immediately, and maybe not for you directly on the spot. But it will, in the long term, not only for you, but for your fellow citizens, software developers.
PS: Of course, as a very smart, sharp and wise software engineer, you might say: “why not eliminate the case that led to such an intricate piece of commenting, by having a better piece of code?”. That is, of course, would be wonderful, and I’d tell that you’ve grasped the Wu Wei principle in programming, and you can now leave the temple. But until that happens, let’s have as much relevant context as possible, because there’s no text without context, no matter how that text might be caused by a messy situation.