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: