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:

Coding Convention conventions:

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?

Design considerations:

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?

Questions to ponder upon:

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.

Ok, so this is my third blog post today. Gotta be a record for me I think.

On Tuesday I will be presenting on the topic of performance optimization at Swenug in Göteborg. This last year I have been working quite a lot with this focus at Admeta. The topic of this talk is: 1 billion web request - response time 50 milliseconds. This is actually not a lie since we have these types of requirements at Admeta. One billion request is quite a high number so I do understand if there is a mild hesitation if it really can be true. But asynchronous requests from multiple high load pressure web sites can stimulate this type of requirements, trust me.

I believe the presentation will be approximately 2 hours, but there will be room for some discussions. I've been at a number of Swenug presentations by now here in Göteborg and I think the atmosphere is very relaxed and nice. I hope for the same nice athmosphere on Tuesday with lots of interesting questions and discussions. So this is what I planed and prepared for my presentation:

1. Load testing process and demonstration

Load testing is of vital importance in order to understand how the load pressure will affect your web site. Scaling with more machines is not always something that you can do hastily if the need arises and it sure does cost a lot of money to do it. So it's good to know a little of what you application could behave in production before you launch it. In this part I will go through the load testing procedure, what to look out for, what data to collect, and give various other hints based upon my experience in the area.

2. Performance Profiling with the Running Mate application

For profiling och optimising, I will demo with a new hobby application that I just recently built: The Running Mate. The special thing about this application is that I have built the domain very loosely coupled with regards to the application layer making it possible to switch the domain layer at runtime. I am basically providing these different types of implementations:

a) The Super Hack: this was the running mate application as easy as I could possibly implement it. Not much design work. But fast?

b) The Overkill Design: This application is a bit overkill since the domain model is interchangeable in runtime. I would say that in most cases, this is not how you would normally decouple the domain layer since the need for it often just isn't there. However, it is very useful if you would like to profile performance with regards to different types of domain model implementations. The architecture pattern is that one of the Domain Driven Design (as described by Eric Evans) which gives the system a very nice Separation of Concern I think. One of the provided domain models is using a traditional Data Access Layer implemented in DDD repositories. The other provided domain model is using the Mindscape LightSpeed O/R mapper which we have used at Admeta for quite some time. As you can see in the link it is providing a bunch of nice features and it is very nicely DDD oriented.

So, I think there is enough substance here for a two hour session with discussion. All code demonstrated during the evening will be provided at CodePlex at http://www.codeplex.com/runningmate very soon.

Andrew Hunt and David Thomas have a written a great book called The Pragmatic Programmer. This book covers so much great stuff!  Most of the time, while was reading it, I found myself sitting with the jaw against my chest in astonishment of how clearly Andrew and David pinpoints problems and recommendations in software development. I think all seasoned developers would have the same feeling since the problems Andrew and David writes about are well-known, but not very easy ones to actually pinpoint and describe.

As a side note, at the Øredev conference recently, I saw Andy Hunt giving an excellent key note speech opening up the conference. There was quite a number of fascinating subjects he talked about and I hope to be blogging on some thoughts on these subjects in the near future.

Anyway, in the book, the writers bring up a term called software entropy as a force very difficult to avoid for developers. When I first heard of entropy it was actually in chemistry class many years ago. An explosion is an excellent example of a chemical reaction that renders a very high order of entropy. I.e. the amount of disorder of atoms in the explosion is very high in the beginning but rapidly goes back to a low level of entropy. Naturally, this is due to the high amount of energy that sets the atoms in motion.

There is a striking similarity with software entropy I think. When things are heating up in a development team and we are as busy little bees to meet a deadline, entropy is bound to be high. Or at least the risk is very high that the entropy gets high. As a cause of this, Murphy’s Law might appear out of nowhere which seems to be a result of just pure bad luck. But often it is the just the result of high entropy, i.e. the disorder tends to get high as we get stressed out and several accidents happens in a short amount of time.

The writers go on with an analogy to city buildings that are of very different quality in different neighborhoods; some buildings being very clean and neat while others in another area are in a very poor state. This is the effect of “a broken window”. If one window gets broken and it does not get fixed immediately, then soon another broken window will appear; and yet another and so on. Soon the neighborhood will look like skid row and criminality increases drastically.

That this is so, even Swedish governments have concluded. I recently saw a news program stating this very fact. And in the local news paper the same very fact got stated about a neighborhood not too far from where I lived. A whole city block is going to be torn down and rebuild and as a result, criminality is sure to drop it was stated. Well, good!

I think there is an absolute truth in this and that it can be explained with our pride. If you are not proud over the neighborhood you live in, you are not going to respect either the buildings or the people that live in them. But if you feel pride over a good, esthetic environment that surrounds you, you take more care of it.

As for software development, we have the same situation Andrew and Thomas states. If you don’t feel proud over the code that is produced in the project and honor its design, the software will begin to rot. If this happens, sooner or later you probably are going to have to throw it all away and redo the whole thing from scratch.

So, as the authors of The Pragmatic Programmer so wise fully states: don’t live with broken windows. Anticipating that the design of the software is a good one, follow it instead of doing small hacks in order to save time. That time you save may very well be 10 times the time lost further down the road when someone is trying to get the once upon a time nice design to work again as it should be.

I know: Software is never perfect and this is not what the authors, neither I, are saying. However there is a great difference between delivering good enough software and doing “hacks” to the system all the time.

Unfortunately there is a driving force that often makes these hacks necessary: the critical deadline of a promise made to somewhere by somebody by someone... But the underlying reason for this is often due to a crappy or not existing project methodology which is a subject that I won’t dig into in this blog post. However, this spring I probably will write a lot more about this.

 

The first time I heard the word ubiquitous, a sigh of utter and ignorant reluctance went through my mind. I figured that such a beautiful but complex word is absolutely bound to bear an over-complicated meaning to something that perhaps might be very easy. And unfortunately, that killed my interest at the time. Well, having understood the importance of ubiquitous language my interest is gained.

So what does it actually mean? Well, a quick search at my favorite place to look for strange words gives me a hint. When adding the word define: before a word, acronym, abbreviation whatever in google, a search will be done at a number of open dictionaries on the Internet. This is nice since the explanation of the word is given in a number of different contexts which gives me a broader meaning of the word. With this search, define: ubiquitous, 5 different explanations are rendered. The one I choose to show to you is this one:

omnipresent: being present everywhere at once
from wordnet.princeton.edu/perl/webwn

In Swedish I would translate this to “allomstädes närvarande” which is even more poetic I think. However, the English translation put us a bit closer on the map as to an understanding of the word, but we’re not there yet. What is omnipresent anyway? Is there really something that can be everywhere at once? Sounds like something I want to be…

Well, speaking about ubiquitous language, naturally we are talking about a metaphor. And after reading about ubiquitous languages in Eric Evans book Domain Driven Design and having combined this knowledge with my own experiences in software development, the pieces actually fall together.

Ubiquitous language is all about sharing a common terminology between people. This is an extremely important ingredient in how we communicate with each other. Without a common terminology there is no way that anyone can explain anything to anyone else. Or at least it will become a very, very difficult thing to do.

Let me take an example of this. Imagine that you are about to explain to you six year old son how he is to ride his new bicycle. Only that you are not allowed to use any words that actually describe such things as pedals, wheels, and stepping on the pedals. Of course you can always point at the things and call them “thingie” but try doing that as you let go of the bike and let him take off on his own.  Well, he is bound to crash the first couple of times anyway so I guess this doesn’t matter that much…

It is hard to find good illustrative examples, isn’t it? Well, I am working on my imagination in this area.

Anyway, in software development we have something that is called the domain knowledge. This is the core business knowledge that is associated with the application(s) to be built. Each company have their own business knowledge and thus also their own specific terminology for it.

However, unfortunately the same terminology is not always used across the company and towards customers. Marketing people will use some terminology when they speak to customers when they originally sell the terrific idea. Then developers probably name those very same things to something similar in the domain architectural design. Then suddenly, further down the road, marketing renames a domain term to something else much cooler and, u-hu, the developers are doomed… They feel that this name change is just not worth the pain of changing it in the software design also. Especially this is common when we are talking the database with live production data. Ouch, do not touch it, it may fall apart and it is deadly vulnerable, the heart and soul of it all etc… Once this name conflict has occurred, the terminology is not shared any longer. Instead all developers have to map their domain names to what marking people means with the provided functionality. This is an utter source of confusion.

Of course, a name change is not the only reason for a mixed terminology at a company and there are certainly most often more players involved than merely developers and marketing people. Lacking communication within a company or misunderstanding of the domain model is just as common source of a fractioned terminology.

So where does ubiquitous “thingie” come in? Well, the terminology that we use to communicate with each other should be as understandable and sharable as possible to everyone so that the same words for describing domain knowledge are used. Then we have a much better chance of actually understanding each other. Trying an illustrative metaphor again; it means that we could concentrate on fitting the puzzle together with the help of the puzzle images instead of trying to do the same thing merely using their geometrical size. At least this is the sensation I get when working in such a domain at a company.

If you know of and understand the domain model and you are about to explain it to new-comers in the project, then my advice is that you start with explaining the terminology being used in a document. This will make it easier for other to understand the domain since they can start by reading this before they get an explanation of what the applications actually does. Otherwise, you will most likely use specific domain language words in your verbal explanations that they have not have heard of before. This will probably make your audience miss the main points you are trying to get across.

Also, by extracting and writing the terminology you will get a better perspective of the domain that you consider as natural and simple but perhaps is not. Most likely, you will find names that are confusing and duplicate names meaning the same thing. If so, revise the terminology so that it is correct and up to date. Make sure that this is the terminology that is used throughout the company by discussing with people. Then you achieve a ubiquitous language which will let you stay focused on the real problems and how to solve these. 

 

I guess this is quite a dramatic blog title statement but unfortunately it is true. I am often cursing over regions I find in other peoples code. This blog post will tell you why generally I don't like them.

Both C# and VB.NET allows for a feature called regions. Regions at class level may look something like this:

Now, the benefit of using regions is that you may collapse them easily when you are not currently working with them. Many regions could then look like something like this

 Of course, in a real scenario, you would have a more real case choice of selecting regions as to group class members. I’ve seen that it is common to group methods and properties etc. according to member accessibility level, i.e. private, protected, internal etc. Also, it is quite common to group regions of common member functionality;  kind of like having inner classes but categorized as regions instead.

To make things worse, C# allows regions to be defined within members too:

So, how come I don’t like this? Well I have a couple of reasons for this:

1.       Regions at class level make the code harder to work with. I think most advanced (lazy ) .NET developers know that the Visual Studio short cut keys Ctrl + M + O collapses all methods and regions in a class. This action gives a quick and good overview of either the members or regions in the class. Even though you may expand/collapse a specific region with Ctrl M + M, it is quite a hassle to have to expand both regions and methods to get an overview of the actual code within the method. I think that an overview of the functionality of a class is best given by the natural language constructs themselves without using regions. Once you start adding regions to you code, you add an additional expand/collapse step in order to be able to start working with the actual code within you methods. This makes the code harder to work with.

2.       Often, when regions are used at class level, it is done because there are too many members in the class to keep track of. This means that the cohesion of this class is low which is bad. Another, very similar principle, founded by Robert C. Martin, is the Single Responsibility Principle. Regions tend to make you violate this principle since classes become too large and contain too much mixed functionality. More on this in a future blog post…

3.       Regions within methods share a common symptom. When regions are used within a method, it is likely done so because the method is very long. Too long if you ask me. Methods should be short and be easy to read and understand. Otherwise they will break what I usually call the Divide and Conquer principle.  In short Divide and Conquer in software design, as I choose to define it, is a major problem split into many smaller problems by decomposing a method into many smaller methods. This is how you understand and solve a major problem a lot easier since you don’t have to be keeping too much detailed information in your mind at the same time.

4.       When you use regions within a method, it is much more difficult to track the actual data flow between different regions. If local variables are used, and not state fields, you can easy see the API for each method. I.e. you see what input data each method needs and what output data it delivers. Regions within methods do not give you this and the code becomes much more difficult to understand.  

5.       Regions within large methods have another problem: if you receive an exception in operation and if you are logging the stack trace of the exception, you have a much more difficult time to track where the actual error occurred. With smaller methods instead, you will at least receive information in which method the error occurred. (…and of course you should not compile your code with the debug flag to true in operation environment…)

Well, these are the negative consequences of regions that I have come up with so far. Of all these negative aspects of regions, I think the potential violation of Single Responsibility and Divide and Conquer Principles are the worst ones. From what I’ve seen, regions tend to make programmers forget that they are developing in an Object Oriented language and instead program as if using a functional programming language. Sure, functional programming languages have their strengths, but improved readability and therefore better maintainability is not one of them.

So. Is there a place when regions actually are ok to use? Well, if someone has placed a region to group some less significant members of a class, I might accept it although I probably would not define the region myself. However, I will never ever accept regions within methods since I think this violates the principle of Divide and Conquer.

Though, I have found one case when I actually use regions myself. I find them excellent to use when I am constructing demos for course material. Regions let me hide code and comments that I don’t want my students to see yet. Alas, I use regions strictly for educational  purpose. Wouldn’t the world be a better if everything just was a big nice demo…. However, it is not. So lay off those regions in your code. Please.

Wow! Emabarrasing. I didn't realize it was almost a year since I made a promise to keep writing in my blog... Ok. Now I make a new promise, here and now: to never make any promises about writing in my blog. That's definitely a more easy one to keep. Allthough I do actually have a lot of subjects piled up that I want to write about and I hope that I can get started at it in november. But that's not a promise..

I have just spoken about Model View Controller at Pimp My Code that Cornerstone arranged. Yesterday in Stockholm and today in Gothenburg, Sweden. It was a great event and my brain is boiling down all the impressions I got during these two days, Both from hearing the other, in my opinion, excellent speakers but also just from the atmosphere during those two days. Hopefully I will get to do this again.

Anyway, I did promise to hand out my code demos in my blog and here they are: MVC demos.7z (167,42 KB).
(Download 7-zip here). I was worried for a while since out of convenience I placed the SQL Express server database (files) in all projects that needed it. Well, the database had a size of about 2 MB (although very little content) which rendered a total size of about 23 MB.. But 7zip did an amazing compressing job so I think I am home free.

Now, some words about the demos. I did write them all this weekend and rather hastily. I did do some refactoring as I created the next demo and so on, but I did not bother to clean up the old ones. But the total code mass is so small as it is so that should be no problem to you. Also, I wanted the demos as clean and simple as possible in order to demonstrate different aspects and flavours of Model View Controller. Hopefully I did manage this. Although I do admit I would have liked to tidy the code a bit. But what the heck. Enjoy or destroy.

Nevertheless, feel free to contact me if you have any question about something. My name is tobias.fjalling and I work at dotway.se. I think you can figure out the rest.

Here my powerpoint slides too: MVC.pdf (0,4 MB)

PS. I just gotta do something abour this crappy blog GUI of mine. This is embarrasing too...

Last week, the Öredev 2006 conference took place. I though it was a great event and I listen too many interesting speakers. I'll probably get back to write some reflections on some of the sessions in later blog posts.  My own workshop session took place last Tuesday and I was assitested with Göran Halvarsson at Dotway for this session. I thought the workshop went fine although I have'nt taken part of the workshop evaluations just yet..  As I been writing previously, the workshop was based on the ASP.NET AJAX July CTP rather than the newly released beta 2 version.  Not that it mattered that much I though since the concepts are the same.

I just sent the workshop labs and the instructions for the walkthroughs to Michael Tiberg, the project leader of Öredev, so they should be dowloadable from the Öredev website soon.  However, I've put in a lot of effort to convert the labs into the beta 2 syntax. This is quite cumbersome since much of the client control documentation still is missing at the ajax.asp.net web site. I'm almost done however, and I promise I will write about my endevaours with this matter in a future blog post.

I'm definetly not the only one blogging this news, but ASP.NET AJAX beta 2 has just been released. This would probably mean that we are not far from a final release. This version is said to be feature complete although there already is a CTP version available with some parts that are being worked on. (I'll probably get back with info on what.) My tip of the hand is 2-3 months.

I've just dowloaded the beta 2 and I haven't yet dug into it to see what changes there are since last CTP. But there is one thing I'd like to reflect upon already now.  When installing the beta 2,  it actually states ASP.NET AJAX extention. So we see that the ASP.NET AJAX will be completly integrated with the regular .NET Framework. My bet is that with time,  ASP.NET AJAX will be a natural part of ASP.NET. Also seing in the release notes, that the <atlas: prefix for web controls is changed to the regular <asp: prefix. Nice.

Oh well. Time to get my hands dirty.

Almost forgot. The .NET Framework 3.0 has just been relased too. But I'll refer to a collegue of mine for this news.