Chris Johnston

If only every boy could own this dart set.

One thing that always amazes me is the discussions that come up when a group of developers start talking about code formatting. I am taking my team through “Clean Code: A Handbook of Agile Software Craftsmanship” by Robert Martin. We just discussed chapters 4 and 5 on Comments and Formatting respectively.

For the most part, everyone agreed with all that was presented in the Comments chapter, but once we got to the Formatting part, the real discussions started. There were three points in particular that people disagreed on:

• How to indent the private and protected keywords
• How to indent continuation lines, i.e., when a line gets too long
• And finally, how to indent, or line up, hashes

You would think that by now this wouldn’t surprise me anymore. I know developers are passionate about their tools and the code that they craft with those tools, and this includes code formatting. What always surprises me is the speed at which developers want to quantify and codify what the formatting should be. I have seen teams waste hours discussing whether a method should be capped at 4 lines or 5 lines.

For me, this kind of discussion is useless and completely misses the point. Developers should be discussing what the code is telling them in terms of refactoring and not the legal length for a method should be. Discussions should revolve around method and variable names, delegation and decoration, and extracting or inlining variables, methods, and classes.

Thankfully, my team is incredible and the final decision regarding formatting was to allow each dev to determine the guidelines for themselves with the overriding principle being readability and clarity.

I am also finding it amazing how quickly the team is adapting to the ideas in “Clean Code” and applying them to the code they are creating. In just a few weeks good method and variable naming and making code readable have become major concerns and are quickly becoming a standard part of everyone’s pairing experience.

The empty lot next to my office has been converted into a parking lot. The interesting thing is how they have gone about doing the construction. The architects and contractors could have brought in the pavers and cement trucks and built a full parking garage immediately. The work would have taken several months to a year and been very intrusive to everyone trying to work near by.

Instead, they brought in a minimal amount of equipment, put down some dirt, graded it, install fences and a pay system and left. That minimal amount of effort, the simplest thing that could possibly work, was good enough for several months.

We had a warming trend and the dirt was starting to get pretty churned up with large ruts starting to form in the middle of the lot. So, the crews came back with some gravel, re-graded the lot and covered it with stones. As I look out my window now, the lot is functioning great. It isn’t perfect, but it is completely functional. Everyday there are cars parked in.

I am sure that eventually the crews will return and pave it, making for a more permanent lot, but for now, it works.

Too often in software development people feel that they have to release the perfect product or, at least, release a fully functioning piece of software. I know were I work this is something we are trying to move away from. In my opinion, it is much better to release the functional, dirt version first and let people play with it. Give it enough time to figure out where the ruts are forming and then go in and gravel.

I have a theory that, with most software, all that is need is about 60%. We only need to implement most of the functionality for people to be both productive and happy, e.g., the gravel version. By starting with the dirt version and working up, we are able to stop when we hit the right point, be that the gravel version or the initial paved version.

I recently did a retrospective with my team which is located in Toronto and Chicago. I wanted to do a fairly traditional retrospective, but having people write things on stickies on posting them on a wall was not possible. Instead, I decided to use Google Docs and created a simple text document. It had the prime directive on the first page and then, when we scrolled down, there was a section for Good, Needs Improvement, and Confused.

This worked out really well as it gave everyone time to think about they wanted to write and also allowed everyone to modify the document simultaneously. I then was able to organize the ideas presented easily by simply copying and pasting them. Voting was done by putting a * beside the idea the person thought was most important. Another great benefit was the fact that we now have a record of everything presented in the retrospective.

After reading Dan North’s post on the Manifesto for Software Craftsmanship entitled “Programming is not a craft” and Liz Keogh’s post, “Why I didn’t sign the Software Craftsmanship manifesto“, it got me thinking about what is the point? What is it that we should be doing as software developers?

Is the point of software development to create clean, aesthetically beautiful code containing clever implementations to business problems or is the point to deliver working software? If you know anything about me then you probably already know what I am going to say, but, for those who are new, I will continue. I personally think the point is to deliver software. Everything else is how we do our job (well, except the clever part).

One problem with universities these days is that they teach people how to create programs. They do not teach students how to create software. When creating software, programming is probably the task that you do the least of. At least programming as it is taught in school. Developing software is about creating a solution that meets the user’s needs and solves their pain points. It is not about the cool heuristic you developed. No one cares about that stuff. They care about getting their work down and whether your software will help or hinder that goal. As such, you spend more time testing code, modifying old code, gathering and understanding business requirements, talking to other developers as opposed to sitting there and just churning out code.

Creating clean code that is easy to maintain and extend is how we go about reaching the goal of delivering working software; it is not the goal itself. I think this is the biggest mistake many programmers make. They mistake the process with the goal. And I agree with Dan and Liz that it is a pitfall for people signing the manifesto.

Now, don’t get me wrong, clean, maintainable code is important for the life of the software that is being delivered and your sanity as a developer. I am currently working on an application that was created by programmers, not software developers, and we are having to rip parts out and rework other parts in order to increase the application’s lifespan. So clean code is important and the goals of the craftsmanship movement are important, but they are the tools, not the product.

This is like a group of Doctors getting together and signing a manifesto for sterilizing their scalpels. Yes, it is important, and at one point in time, it was very much needed. But sterilizing tools was never the end goal, keeping their patients healthy and alive was the point and sterilization was only a means to that end.

If your goal is delivering working software then you only have time to code until it is good enough and test until it is good enough. There is no time to be clever or to make it perfect (there is no such thing anyway). Create the initial code using things like the SOLID principles and TDD, but in the end, if you haven’t delivered software to your client and stakeholders then you are not doing your job and you have missed the point.

One trick that I use when I can figure out an API or how to test something (like testing controllers that use AuthLogic) is to look for the particular method––in this case activate_authlogic––on github and look at how other developers use it.

One of the problems with tutorials and documentation is that it never shows how to test code that uses the gem. This was the case for me today with AuthLogic. I was having a hard time figuring out where to put activate_authlogic and the code for logging in a user in order to test a controller. A quick search on github provided more than enough examples for both RSpec and Test::Unit.

One problem I have seen on several projects I have been on, including my current project, is that the developers and the business stakeholders use different vocabularies when describing things. Eric Evans, in his book Domain-Driven Design, stresses the importance of having a shared vocabulary where the devs use the same language as business.

As an example of this, I recently had to make a change to my cell phone account. It was originally under my wife’s name and I had to move it so it was under my name. I went into a Roger’s store and attempted to describe what I wanted. The result was several strange looks. Eventually the sales person asked if I need to do a “Transfer of Responsibility?” To which I said yes. Immediately there was understanding between everyone involved. We were speaking the same language.

Having a shared language can be problem within a single application, not just between developers and business. The project I am working on right now contains a Person model that handles people. In the database, it has a People table. The problem is that every where else, we use the term Member and there are a few places where the term User is used. This makes working on the code confusing along with trying to describe it other developers and business.

The solution, contrary to what developers believe, is to learn the language that your clients and stakeholders use. They are the domain experts and they are the ones who will eventually use the application your are building. As such, one of the best methods of guaranteeing that you build the right solution is to learn the language of the domain in which the problem you are solving resides.

The biggest advantage of doing this is that it allows the developers and the users to have intelligent conversations without one group having to translate. Everyone know what everyone else is talking about and it allows decisions to be made quickly and for problems to be found and understood quickly.

Imagine a scenario where you have two developers discussing a particular user story. The discussion is over a bit of confusion and ambiguity in the story. A business user walks by and overhears the two developers talking. Instead of walking past, shaking his head at the foreign language the developers are speaking in, he is able to jump in and point them in the right direction. The reason is because he understands what they are talking about. Additionally, the developers very quickly understand the solution provided and don’t need to translate it.

In short, I believe that a non-developer should be able to sit down at a developers computer and start reading and understanding the code in front of her. The reason is that the objects, methods, and classes should all reflect the language of the domain. They may not understand the syntax or logic, but they should recognize the operations, names, and language as their own.