Comments in code, you can’t live with ’em, you can’t live without ’em. Depending on who you ask, comments are a crucial form of documentation without which most source code would be unusable. Others might say that code comments are, at best, an administrative nuisance or, at worst, dangerously misleading as they inevitably lose sync with the source code they purport to clarify. Reality, of course, lies across a spectrum between these extremes. Code comments, in-and-of-themselves, are neither helpful, nor hurtful. It’s the content of the comments themselves and how they relate to the reality of the source code itself that makes them valuable (or potentially harmful.)

If you’ve attended elementary school in the States, you should be familiar with 5WH, the building blocks of questions: Who, What, When, Where, Why and How. These six words cover the gamut of questions you can ask and provide structure to information sharing. So, what happens when you apply these questions to comments in source code and use them to direct the information you need to share?
Continue reading →