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 5 Formatting questions:

1. How many characters per line do you think is maximum?
   
• What resolution do you use on your monitor?
2. How do you typically choose to group code in your classes?
3. Do you place a caller and callee method close to each other or group them in some other way
4. Where do choose to declare your member variables?

1. Do you agree with that "protected variables" should be avoided? Why / Why not?
2. How many rows do you think a class can have before your warning bell start to ring that it might be too big and do too much?
3. Is there any reason you can think in which instance variables should be placed anywhere but at the top?

1. The chapter emphasizes quite a lot on grouping code together that belong together. (Vertical Density p79, and Conceptual Affinity on p 84)
• What different group categories do you use and why?
• Where do you draw the line between grouping code with regards to functionality in a class and extracting a group to a new class (according to the Single Responsibility Principle)
2. Do you agree upon that all developers in the team should agree on single formatting rules.
• Where do draw the line of agreement?
• How do you select which rules to apply? Voting or something else?
3. What on earth is a ”Hollerith limit”?

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. 

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 2 Meaningful Names

1. What do you think is the characteristics of a good name?
2. Do you take IDE Code Completion into consideration when labeling namespaces, class names and its members?
3. Have you reflected upon "noise words" in names before?
   
4. If you have a class property of type int named Age, but you discover that you would actually want an Age property of type string as well. How would you handle this?
5. Are you or have you been using Hungarian Casing? Why? Do you agree with the books statement that it should not be used in modern languages?
6. Having a prefixed I for interface is an established Microsoft convention. Do you agree with this? Why?
   • Extra (Design considerations): Interface vs Base classes [1], [2], [3], and [4].
7. Do you think "Duck Typing" is something good and do you see Duck Typing as possible in a typed language as C# v3?
   • How far should we utilise the support for Duck Typing in CS 3?
8. Would you consider complexity of code as a beautiful thing or do you agree with the books ways of seeing such practices to write complex code deliberately as a personal quest to show off mental capabilities?
9. Is there any benefit of using constructor (or a static factory method that produces the object) as a way to inject dependencies compared to properties/mehtods?
10. Design: So you find the concept of Value Object as a useful pattern?
11. What is your opinion on PascalCasing and camelCasing?
    • Do you have a deviating opinion from Microsofts recommendations of when to use which?
12. Are there any rules in Chapter 17 that you think originates from this chapter?
    • Is there any rule that you are missing from what you have read in this chapter?

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

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 1 Clean Code questions:

1. Before reading, take a moment to reflect what the concept of Clean Code means to you.
   • Is there anyone of the different "guru's" description of Clean Code (p7-12 + forword) that do you think lies closest to your own definition of Clean Code?
   • After having read the chapter, has the reading changed your conception?
2. What is your experience / opinion of code generation tools or any other higher abstraction level of programming (4GL)?
   • Do you have any good or bad experience of building your own code generator (in some way)?
   • Where do you think we are heading when it comes to abstraction levels in languages and tools?
   • Do you consider this to be a bright future for us developers?
   • extra: What do you think of Joel Spolskys described "The Law of Leaky Abstractions"?
3. Have you experienced something like "the Grand Redesign in the Sky" and how did that end?
4. What is / has been your explanation to having written bad code (as we all have done!) in the past?
5. Do you think it is suitable for us as a team to align to a "School Of Thoughts" (p12) or do you see any better path to having a more uniform clean code conception?
6. What do you think of "the Boy Scout Rule" (p.14) applied to code?
7. Are you familiar with any or all following Principles of Design (S.O.L.I.D.) (p15):
   • SRP - The Single Responsibility Principle
   • OCP - The Open / Closed Principle
   • LSP - The Liskov Substitution Principle
   • ISP - The Interface Segration Principle
   • DIP - The Dependency-Inversion Principle
8. What do you think is the status of Clean Code at our company?

As a side-note, Robert C. Martin and Joel Spolsky, the two people basically mentioned above, seem to be disagreeing a lot these days (excellent summary here by Niclas Nilsson). I guess they have not read my writing upon the Truth vs the Truth... They seem to have made up somewhat in the end though.

Reading the Clean Code book, as for reading any book really, is not just about reading and understanding. It is also about reflecting on what is stated and translate it into your own context and experience. I hope that these questions will help you do this.  

In a previous post entry I wrote about my idea of starting a Clean Code study circle at work. In this blog post I will collect an overview of the book as we continue our study circle providing links to blog post containing questions for each chapter. I've also posted some guidelines and recommendations for others who are thinking of starting a study circle. I will be updating the list below with links as we go along with our study circle at Admeta during 2009.

Study Questions chapter overview

1. Clean Code: questions
2. Meaningful names: questions
3. Functions: questions
4. Comments: questions
5. Formatting: questions
6. Objects and Data Structures
7. Error Handling
8. Boundaries
9. Unit Tests
10. Classes
11. Systems
12. Emergence
13. Concurrency
14. Successive Refinement
15. JUnit Internals
16. Refactoring Serial Date

Some Guidelines for Starting a Study Circle

If you are thinking of starting a study circle at work, here’s a couple of practical advises based upon our experience:

1. The topics in each chapter can potentially lead to discussion that lasts for days... But try to limit yourself to the time set out for it. The meetings is not necessarily about reaching a final agreement of every discussion. Instead, look at is as the beginning of a journey to some kind of agreement of a mutual understanding of what clean code is.
   
   
2. During the hour, we summarize each sub chapter. I.e. some volunteer person for each subchapter summarizes in his own word briefly and objectively what was written. Once done with this, the same person gets to be the first to reflect upon the content. A discussion can follow afterwards.
   
   For us, such a summary/discussion of the chapter would take more than an hour (in both groups). So it is a good idea to tell people in advance what subchapters they think should be focused on in each chapter. Start with these subchapters when you meet!
   
   Most likely, you will not have time to discuss the questions. But you may sneak a question in at a sub chapter discussion.
   
   
3. As a follow up to the meeting, use some kind of survey tool to poll questions discussed in the meetings. This way you will actually get a statistical backing up of what people think based not only by those who are the most eloquent with words.
   
   I tried out using SharePoint surveys but I don’t like the tool. (I might come back with a little blog post rant on this…)
   
   
4. If there are many developers, split the group into smaller groups. It is easier for all people to get a chance to say something if the groups are smaller. The person who set up the group will participate in both groups and act as the meeting coordinator and bridge between the two groups.
   
   If several groups are used, I think it is a good idea to rotate the people in it every other or third meeting. Everyone should really know everyone in good working teams.

At Øredev in November 2008, I got the opportunity to listen to Robert C. Martin, also known as Uncle Bob. I have been a fan of his work for many years ever since I read his book Agile Software Development Principles, Patterns, and Practices. A few years later when the C# version came out I took the opportunity to reread many of the chapters. To me, that book became a eye opener to a new way of working with code. And I think I am not alone. For instance, it seems to me like much of the ALT.NET movement gets a lot of inspiration from topics found in this book. Like for instance the excellent description of the 6 design principles, now commonly referred to as S.O.L.I.D.

Anyways, in 2008, Robert Martin came out with a completly new book called Clean Code: A Handbook of Agile Software Craftsmanship. Naturally, Clean code was his chosen topic at Øredev for both his keynote and the session on Functions (chapter 3). Robert Martin proved to be a passionate speaker so I was not disappointed. Neither have I been disappointed in this new book so far. Since Øredev I have read about half the book and I truly feel that it is a gold mine to read for any professional developer.

But I kind of stopped reading a couple of weeks ago since I had this great idea. But before I tell you what, I’ll tell you why. That’s usually a good start.

The big WHY

The concept of “Clean” is often defined per developer

This is a bit unfortunate but my experience is that we developers all have different opinion as to what clean code really is. We all get our little habits and our own way to keep our code clean and readable to ourselves. It happens that we shun the sight of other people’s code since it simply is not clean. As in our definition of clean that is.

If only, we could keep our noses glued solemnly into our own written code. Unfortunatly, this is not so.

The common code base

Professional programmers usually don’t work isolated from other professional programmers (although it happens). Most often you share a code base with others and you will have to dig into and work with other peoples code. This is usually where a developers' nose start sneering since, "no way, that code is clean!"

Imagine this sneering nose developers name being Robert. So what does Robert do when confronted with such ugly code? Well, he would probably sneak in a bit of refactoring of the code with the sole purpose of making it clean. That’s ok and quite normal for any programmer to do. So it should be ok.

The only problem is that when Joe, who originally wrote the code, wants to work again with the submitted, now clean, code, he finds the code to be … unclean.

What does Joe do? Well, you guessed right: refactor a bit back to “clean” state. With a big grin of proudness, Joe will resubmit the now clean code into the code repository.

Later when Robert comes back to this code, what does she do? Well perhaps refact............

Verbal Communication

Naturally, we developers aren’t idiots (although it may perhaps seem so occasionally to non-devs.) and we do have a mouth for other purposes than to shovel food and drinks into it. So in the end, Robert, or Joe, will walk over and talk to eachother. This is where the "big discussion" may start. What is clean and what is not clean code.

It may sound like it would be a heated and most dreadful debate. But I think most developers actually like discussing these things. As long as you are able to convince the other guy of how beautiful and logical your clean code is. However, most of the time, this agreement does not occur and the constant battle of Clean Code carries on.

In the end, developers may stay away from other peoples code since it is tainted by uncleanness.

The Contract

Naturally, the previous description is not a successful situation to have at a company. The code base must be shared for lots of reasons; work scalability and fresh influences to name a few. So many companies bring out code policies, written in a document for all developers to see and sign on. In blood. Code inspection tools, like FxCop, will run at night and report to everyone in the morning if someone has violated the signed contract of Clean Code.

Naturally, the contract has got to come from somewhere. There are a couple of different ways

A)     The company chief architect(s) brings forth the document for all developers to follow.

B)      All developers join in big battle lasting for days and come up with a final agreement.  

C)      The company borrows someone else’s contract.

Naturally, C) is the most common option. But there will always be room for B) and A) since there are domain specific stuff that still can be agreed upon.

The idea – the WHAT

At Admeta, where I work, we are using the Scrum project methodology and we are fairly agile in the way we work. We are using model C) as in the Microsoft conventions and guidelines and we also have a wiki page with further conventions agreed upon, i.e. B). We do not believe in the A) alternative.

So naturally when I began reading the book, it became clear to me that I would be doing an awful lot of referencing to the book when discussing clean code with my collegues. Very soon I thought, my colleagues would get very tired of both me and Uncle Bobs opinions (although they all heard him speak at Öredev) and tell me to put a sock into my mouth... What a dreadful scenario!!! So naturally, I was forced to get an idea. And thus it came to me one beautiful day:

The idea: So why not try to make everyone read the book and we will have a discussion for each chapter? I have previously been participating in a group doing exactly this at Dotway with the GOF Design Pattern book. To me Clean Code seems like a perfect topic and we could probably gain a lot as a company and individuals if we spend some time doing this together.    

The idea – the HOW

Said and done. I talked to my colleagues and every developer on the company has now joined. Everyone has got an own copy of the book (it’s actually very inexpensive) and we get an hour once a week on company time to do discussions. Reading is done on spare time, but hey: it is fun reading! Besides, each chapter is quite small and would take little time to read.

So this Thursday, we’ll have our first Clean Code discussion meeting. As a preparation, the meeting attendees will have to read Chapter 1 of the Clean Code book. I have also given them the following questions to reflect upon:

1. Before reading, take a moment to reflect what the concept of Clean Code means to you.
   • Is there anyone of the different "guru's" description of Clean Code (p7-12 + forword) that do you think lies closest to your own definition of Clean Code?
   • After having read the chapter, has the reading changed your conception?
2. What is your experience / opinion of code generation tools or any other higher abstraction level of programming (4GL)?
   • Do you have any good or bad experience of building your own code generator (in some way)?
   • Where do you think we are heading when it comes to abstraction levels in languages and tools?
   • Do you consider this to be a bright future for us developers?
   • extra: What do you think of Joel Spolskys described "Law of Leaky Abstractions"?
3. Have you experienced something like "the Grand Redesign in the Sky" and how did that end?
4. What is / has been your explanation to having written bad code (as we all have done!) in the past?
5. Do you think it is suitable for us as a team to align to a "School Of Thoughts" (p12) or do you see any better path to having a more uniform clean code conception?
6. What do you think of "the Boy Scout Rule" (p.14) applied to code?
7. Are you familiar with any or all following Principles of Design (S.O.L.I.D.) (p15):
   • SRP - The Single Responsibility Principle
   • OCP - The Open / Closed Principle
   • LSP - The Liskov Substitution Principle
   • ISP - The Interface Segration Principle
   • DIP - The Dependency-Inversion Principle
8. What do you think is the status of Clean Code at our company?

I think these questions will be more than enough to discuss for our meeting so we will probably end up choosing the most interesting ones to discuss. I am truly looking forward to it.

Btw, I'll be continuously posting my questions for each chapter on this blog. So stay tuned if you are interested.

Some 20-25 years ago as a teenager in School, a teacher once told me and the rest of the class the following metaphor.

Two persons look at a roof top and distinguish a bird sitting at top of the roof. The distance is far so it is difficult to see the details, but one of the persons suddenly says: "what a beautiful peacock!" The other one looks at him bemused and says "that's not a peacock. It's a rooster!"  Then the two persons burst into an argument on this matter which lasts for quite some time.  

What my teacher then told us is something important I think: Sometimes the truth is different for different people, but each version is still a truth. It is important to remember, and respect, that there may be different versions of the truth which are correct in their own way.

I have come to reflect upon the essence of this very often over the years and I feel I would like to write some fine grained aspects of it:

The truth is context dependent and it is not always absolute.

Both persons actually believe themself to be right, and in a fundamental way, they are therefore both correct. In order to understand this perspective it is vital to consider the context. The context in this example is quite complex since you must take into account things like eye sight capability and what the actual conception of what a rooster and a peacock are. Nevertheless, the person with poorer eye sight or perhaps lesser bird knowledge, still perceive his belief according to his own context. That makes it a truth. Valid in a specific context.

Most likely, you are thinking the same thing as I have been thinking for so many years: There is always an actual correct truth to be found. Take mathematics which should be as a good example. There is always a correct answer to a calculation, right? I mean, 1+1 will always be equal 2, don't you think? However: If the context is Boolean logical mathematics, 1+1 is actually equal to … 1. So whatever truth you think you have, someone may pull a rabbit from a habit bringing a completely different context into the picture which will make your established truth completely wrong.

If the two persons go closer to the building they probably will discover that another truth exists. This is actually where the story continues:

The two men found they could not reach an agreement so they decided to walk closer to get a better look. Soon they realized that it was not actually a real bird, but a statue of a bird. More than that, once they got to see the details neither of them could really tell what kind of bird it was the artist had meant to depict. 

Ah! Now we are getting closer to reality I think. Certainly there are better truths that can be found when digging deeper. But very often we find ourselves in a situation where we have to accept a good enough truth. A truth that works for the applicable context. This is a practical truth.

Let us turn our attention in another direction for a while.

Always choose the most important topic in a discussion.

Have you ever found yourself having several discussions going at the same time with someone? Well, unfortunately it occasionally happens to me. Before having reached a consensus from an initial disagreement of opinions, the next disagreement comes up. To make things even worse, the knot to untie the first disagreement depends upon the second disagreement to be settled first. This can continue in an evil spiral of disagreements until you find yourself arguing over 5-6 very different things at the same time. I always hate when I find myself in these discussions since there are too many variables to categorise and sort out. I beilieve that this is one of the obstacles that make discussions such a difficult art. When this happens, there is ususally a call for a time-out in the discussion I think.

But let us turn our focus back to the two persons again. The first person said that it was a beautiful peacock. A bit speculative perhaps, but his main point was probably that it was beautiful, not necessarily that it was a peacock. This would be the main sensation he had and most likely the feeling he wanted to communicate. But by doing so he found himself ending up in a discussion that probably had nothing to do with his original sensation. If the two persons enjoyed the bird discussion and considered it as meaningful, perhaps it was a fruiteful one. However, I think they hit a a side-track and discussed a less prioritised issue. If this is so I think both persons could have given in earlier by saying something like “oh, perhaps you are right”. Then they could have focused on the original and probably more important message: beautiful or not…

Although the story is a vague example on this, I think we often do tend to discuss less meaningful things just because of curiousity or a sheer willingness to be right. Instead, we should focus on the stuff that matters within the important context!

I’ve met some people who loves throwing arguments in a heated discussion and who might even provoke a person in order to get it. I’ve also come across some people who have even lied about their true opinions in a discussion since they wanted to test the opponents’ arguments. This discussion tactic may be a dangerous road to walk. In the end the person often end up confessing that he had not really been arguing with his true mind. If these types of discussions keep reoccuring with the same person, unfortunately my trust fades away. Do you want to spend your time discussing something with someone in whom you have no trust?

So let us get back to a final aspect of truths in a discussion.

Considering someone elses truth is about showing respect and having patience.

With this aspect in mind it becomes a whole lot easier to actually listen to people in a discussion/argument. Quite clearly, the more confident of an opinion we become, the more difficult it is to be open and appreciate different ways or slightly different truths.

I think that listening and appreciating other peoples truths is the most important ingredient in a discussion. You will never truly "win" a discussion if you don't pay the other person respect by giving him proper feedback showing him that you are actually listening and understanding his truth. And by saying paying respect, I dont mean shoveling a line like "yes, perhaps you are right, but..." and then quickly head on to your main point. That's nothing!

I would dare to say that showing that you listen to someone is a very physical thing. People who are good at this highlight this attention using their whole body. We normal mortals mostly have to stick to the use of our eyes. Your interest and intention should very clearly be shown when you meet the other persons eyes. A bit of a magic trick to that wordless communication phenomena, but eye contact communication does actually work in this sense. That is how you are showing your interest in his version of his truth. Not by opening your mouth quickly and say something stupid like "yes, but"...

I also think it is best if this effort is sincere and not just a plan to get your own point across. Be open to that you both have a version of the truth (or even that you can be wrong) and you will both probably gain a better understanding of a deeper truth in the end.

I firmly believe this is the key to successful communication and I am constantly trying to become better at it myself. It is not easy in the heat of the moment in a discussion. And I must admit I sometimes fail due to lack of patience... But, hey, the road to perfection is a long and fun one to walk!