Clean Code – Are Comments Required?

Sharing is Caring

On LinkedIn, I noticed a question that didn’t really have any answers or additional comments. “If I write clean code, do I need comments?” was asked by the user on the discussion board.

In an ideal world, there would be no need for comments because the code would be expressive enough that any programmer could easily grasp the concept. Comments should only be used when we are unable to clean the code more, and have it more expressive as Uncle Bob would say.

Comments should only be used to signify code, functionality, libraries, etc that aren’t clear or perhaps ToDo if your IDE supports them. Often code evolves, gets deleted, added to or whatever, but the comments are left in neglect and often end up very wrong about what the code is doing. In Clean Code, Uncle Bob describes this problem in a few words: “The older a comment is, and the farther away it is from the code it describes,the more likely it is to be just plain wrong.”

In an ideal world, you wouldn’t need to write comments, but we don’t live in an ideal world.I think that you still do need some comments, but that the number and frequency of comments should significantly decrease. Comments are a necessary evil sometimes, especially around exception handling or something that isn’t very easy to make clear. Always remember, that we need to be disciplined in updating comments as we modify the code surrounding the comments.

Sharing is Caring

Brian is a software architect and technology leader living in Niagara Falls with 13+ years of development experience. He is passionate about automation, business process re-engineering, and building a better tomorrow.

Brian is a proud father of four: two boys, and two girls and has been happily married to Crystal for more than ten years. From time to time, Brian may post about his faith, his family, and definitely about technology.