This blog post is part of a series of blog posts concerning a Clean Code study circle that we developers at Admeta are persuing during 2009. Here you can find an introduction concerning the question why we are doing this and here you can find an overview of all chapters as well as some study circle recommendations.

Chapter 4 Comments questions:

Reading quiz:

1. What does Robert Martin mean when he writes that comments lie?
2. This chapter contains 8 different categories of good comments. Which ones do you remember?
3. Likewise there are 18 categories of bad comments. Which ones do you remember?
   Chapter 17 "smells and Heuristics", lists 5 categories of bad comments (p.286)  

Questions to ponder upon:

1. One good comment is the "todo comment" which has tooling support in Visual Studio.NET. There is also tool support for using the "Hack" comment (e.g. //Hack: this code should be cleaned up when there is time for it). Do you think this is a good comment to use if you don't have the time to clean the code to a good design?
2. Setting a function comment has the positive side effect in Visual Studio that the comment is visible with the so called Intellisense (auto-complete). However, there is a limit to how long a sentence can be in order to be showed in the intellisense. One could argue that a valid comment would need to be long in order to say anything that the function name itself does not convey. Do you agree or disagree?
3. What is/has been your reason for commiting commented-out code to the source code repository?
4. If you are implementing an algorithm that is more complex than usually, do you prefer to document that algorithm as pseudo-code as a comment close to the implementation of it? Why/why not?

The context of our study sessions is restricted to .NET and C#.