At this point I’ve set a lot of the groundwork required to understand what all this Software Craftsmanship is all about. I hope you’ve picked up some of the books I’ve mentioned and had a chance to flick through them. At this point I’m going to start to cover the areas in the Clean Code book from Robert “Uncle Bob” Martin and also highlight where his videos help reinforce the books points.

The first chapter is simply called Clean Code and the first quote really does set the scene.

You are reading this book for two reasons. First, you are a programmer. Second, you want to be a better programmer. Good. We need better programmers.

This is so true in all programming technologies and none more so then CFML. I mentioned earlier most of us are self-taught, so it’s easy for us to learn how to do the right thing wrong, rather than the right thing right. We know no better, and still we need to start looking outside of our comfort zone. This is something that every developer, every day, should be doing: pushing their comfort zone otherwise you’re no good to any one, IMHO,

There is an interesting story at the start of this chapter they may resonate with many old time ColdFusion developers. About using a product that everyone wanted to use like CF back in the late 90’s but as the release cycles took longer and bugs didn’t get fixed the frustrations grew and the people started to stop using it and the company went bust. The story continues to say that Uncle Bob meet with an employee of the said company and it appeared that bad code caused the company to shut down, they were adding new features on top of bad code and it became to much to support and slowed down the whole process. So it was bad code, which caused the company to go out of business. Those of us who know the story of ColdFusion’s move to Java know that 6.0 was a bad release and if it wasn’t for 6.1 it would have been dead then. If I’ve heard correctly the team creating the CF version where also the team that created the C++ version but were learning java as they went and this is why some of the decisions have come back to bite ACF in the arse. There is hope that CF12 will resolve this but that is a couple of years away yet.

So we’ve all had to put a hack in to some code to get it out to release and said we’ll come back to fix it, we should all know LeBlanc’s law – Later equals never. You’re never going to get the change to come to back and fix the code you should have done right the first time. This is called technical debt and I’ve read of teams that have a “Technical Debt Back Log” and are happy to put things on this. I don’t think a client will ever be happy to pay you to fix the bad decisions you made when you could have made the right one the first time.

The thing about messy code is that is slows you down, first by actually reading through it and trying to understand it. Then by having to make the change you need to make and being compounded by the current code there already and not wanting to introduce any additional bugs, but no-dealt you will and there is no way round it due to the mess you have to work with. We know that as the mess increases the slower we get and the management then decide to add more people and then you have new people who see the mess and they don’t know what is the design intent and so if they copy the areas where we have “broken windows” then this makes the problem worse.

Everyone’s definition of what clean code is differs and this chapters captures some of the biggest and respected names in the software industry and their thoughts on clean code some of them conflict. For your team you have decide what is right and what is wrong (Your broken windows) a first step for this can be a coding style that you all agree one you all have to agree else this isn’t going to work and people have to agree to back down when they are out numbered and change their thought process yes this may slow you down but with time you’ll get up to speed and then looking at anyone code in the system means it could have been written by anyone. Now for a green field application, maybe you don’t need a coding style you may agree the basics but the code it self shows the style and anything different will stick out and will need to be fixed as soon as possible. (The CleanCoder video episode one []  discusses this further)

Most of us will always be in brownfield, and we’ll never get “That great rewrite in the sky” we have to use the boy scout rule, which says that you’ll leave the camp ground in a cleaner state then you found it. This should be the same for code if you’re working on a function tidy it up (not the whole file, just the area you’re working on) make a variable name better, if it’s doing more then one thing split it out, does it have enough test coverage, can you increase it with different scenarios that may of come to light?

Uncle Bob ends the chapter in a nice way by reading the book it will not instantly make you a great programmer but it will help you learn the techniques to become one. He also reminds us to practice, and this is very important and something that many of us don’t do.

My take on clean code is very similar, but I have a real anal view on how it should be lined up I know it has driven some of my newer team members mental but as time as gone on they have grown to accept it and love it; as it makes the code a lot easier to read. As a developer you will be reading code more then you write it and so having a decent layout makes it easier. The concept I have learnt is called Gestalt (feminine commonly shape, form; Figur, Person: figure) and it is about how you brain processes related information – the form, with the layout we have in our code base it makes it very easy to spot mistakes as they stand out from the rest of the code. We also us leading commas as this again make spotting mistakes easier but also commenting out a line is very easy and we’ve found it means less brain processing and work when you need to do this.

Here are two images, of the open source software BlogCFC the as it currently sits in source control, and my version where it’s lined up and functions extracted to make it easier to read – notice the reduced comments they are not needed, more on this in another part to the series.

before after

The point to remember here, you will also read more code then you will write. Make it easier on your future self and fellow future developers by taking more time about the layout of the code, you wouldn’t read a book if the layout was all over the place would you, well you might but your wouldn’t enjoy it as much.


2 Responses to Software Craftsmanship – for CFML Developers Part Four – Clean Code

  1. Aaron Martone says:

    I used to have this problem in my onApplicationStart() when it came to going through the steps to properly ensure the startup of the application.

    In time, I found it easier to simply create an AppService object that I could fire off method calls and pass needed reference vars and objects in order to perform those actions “elsewhere”. After doing so, the naming conventions on the methods were obvious (at least to me) to indicate what was being done at those steps. This helped me to be able to remove more commenting as well.

  2. matt says:

    You could simplify your blogCFC code more if you’re on CF10 and turn it into a full script component (which compile faster than tag based cfc’s), by using new utils() or createObject('utils') instead of createObject('component','utils') and also by using {} instead of structNew()

    Just my $0.02

Leave a Reply

Your email address will not be published. Required fields are marked *