This post is about Chapter 4. Comments from the book, Clean Code by Robert Martin. This chapter along with the rest of this book has a strong relationship with the course because it is all about how to write clean organized code. This chapter is on writing effective comments. Rather than long drawn out chapters of plain text, the chapter is split up into many subheadings with even more sub-subheadings. I find this format very useful because it splits up and organizes the information so that it is easier to read and understand. Many of the subtopics have many examples to go with them. This makes it even easier to understand what they are trying to say. The chapter is split up into into two main sections/subheadings, “Good Comments” and “Bad Comments”. Each have many subheadings to them such as “Legal Comments”, “Explanation of Intent” , and “Informative Comments” under the “Good Comments” subheading. “Redundant Comments”, “Misleading Comments”, and “Mandated Comments” under the “Bad Comments” subheading. I selected this article because we have not gone over proper comment writing in my classes (or at least I have not), and I think it would be an important thing to learn for future jobs and class projects. I have found the information in the article to be very direct and informative. As said earlier, it is split up into various subheadings with subtopics so if you are debating whether to add a certain comment into your code, you can go right to topic of the exact type of comment you are looking to add. I have learned about “noise comments” which is basically putting comments that are not needed such as /** Default Constructor*/ over a constructor. I would do this because I would typically like to explain everything in the code but things such as constructors explain themselves. Another is “mandated comments” where you give a javadoc at every single function. I would always do this but it only creates clutter. An example of a “good comment” that I have learned about is “warning comments” where you can warn other programmers of certain consequences for example leaving, “// don’t run unless you have time to kill” above a test with a really big file. Another example of a “good comment” is “amplification” where a comment can be used to amplify the importance of something that may not seem that way. I will be able to apply this knowledge in the future with projects and work to provide clean uncluttered code and powerful, efficient comments.

From the blog CS@Worcester – Austins CS Site by Austin Engel and used with permission of the author. All other rights reserved by the author.