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#. 

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.

Questions: Chapter 3 Functions

Reading quiz:

1. Why should functions be small?
2. Why do function arguments take a lot of conceptual powers?
3. How do you avoid too many parameters in a function?
4. What is temporal coupling?
5. When would you make a difference between returning a value from a function and setting the value as a class field within the method?

Design considerations:

1. Is it ok to have many different levels of abstractions within the same method / class?
2. How do you see C# v3 Extension Methods fit into what Robert Martin writes in this chapter?
3. If you don't use flag arguments, and instead use several unique methods, how do you avoid duplication in the code?
4. Do you see any design choice in which error codes code be used and still avoid creating a dependency magnet, as well as avoiding OCP violation?

Questions to ponder upon:

1. Functions are also sometimes referred to as methods (no return value). Why does not Robert Martin mention methods in the chapter?
2. If functions should only contain 6-8 lines, would you prefer not to waste space using {} when you have an if statement followed by a one line block statement?
3. Say that a function is doing several things, but these things can be considered as one thing on a higher abstraction level. How do you label that function if you can't find a good name to describe that higher abstraction layer?
   

The context of our study sessions is restricted to .NET and C#, thus the nature of the questions above.