Coding Notes

A few months ago I was working on some code that someone else had written. I was trying to add a feature into a class and couldn’t seem to figure out how the class worked, and thus couldn’t figure out where or how to implement my addition. After reviewing the code for a while I started to understand what was going on in the code and had a good enough understanding of it to then implement my new feature. The problem was since I then understood what the code was doing and how it worked I also felt compelled to restructure it, perhaps in a more logical order, or just change it so that it would be easier to understand later on. My problem was that after thinking about a new way to structure that class I wasn’t really certain about why that would be a better alternative, it just seemed better. So after wondering why it seemed like a good idea I decided to do some research into how to write “better” code, and why “better” code is “better”. My research ended pretty quickly as I remembered a few of my workmates talking about the book “Clean Code” a while back and how it discussed what makes “better” code. So I went to my local bookstore, picked up a copy, and started reading it.

Clean Code: A Handbook of Agile Software Craftsmanship was written by Robert C. Martin who has previously published books (which I have not read) on software engineering. He opens up Clean Code with the classic “WTF” comic of software quality, you know, the one that describes good code as code that produces the least “WTF’s per minute”. This is a really good example, since, that is exactly the kind of experience that got me to pick up the book. Martins purpose for the book is to present ideas on how to clean up code, and reduce the “WTF’s/Minute”, and make it easier for others and you to understand and modify later on. The first thing that Martin discusses is the problem of bad code, what it is, how it happens, and what the long term results are (maintenance, lots of maintenance). He then quickly transitions into a discussion of what clean code is, he asked several senior and well recognized software engineers what clean code is, and then lists their responses to get things started. After a brief overview of what clean code is, its off to the races, in depth analysis of clean code techniques and plenty of code examples to go along with it.

By far this book is not a quick read, or at least it shouldn’t be, most of the code examples that Martin gives are given first in the difficult code to understand context and then cleaned up into a clean code example. This method of actually showing the before and after code samples, if actually read and understood, gives immense meaning to the ideas that Martin gives on how to produce clean code. That being said, it is because of these code samples that this book is a bit of a slower read. Martin also encourages his readers to take the time to understand the code changes, warning that by not doing so you will miss out on the real understanding of why these code changes are occurring.

Martin begins the clean code concepts with fairly cosmetic issues, naming conventions, class and method sizes, comments, and formatting. These issues are fairly light on the technical scale (with class and method sizes being a bit more difficult) however, Martin does a good job of showing the benefits of implementing these clean code concepts. Then Martin goes into a discussion of more technical issues, error handling, objects and data structures, crosscutting concerns, system wide organization, testing, and even some discussion of concurrent programming. All the while he discusses not only good principles but why they are good principles, and gives examples of how to apply them. On some issues Martin admits controversy surrounding issues and clarifies why he came to his conclusion, as well as what others think. Martin then finishes the book with three chapters which take entire classes from well know API’s and dissects them into better, cleaner code, using the principles previously discussed in the book. These sections, as Martin states, are necessarily slower to read, given the large amounts of code and the complex changes. However, by slowly reading through them and understanding the changes being made it helps to bring together all the concepts of the book and shows how large sections of code can be understood and cleaned.

In the end of the book are several appendices, one is an in depth chapter long analysis of some concurrent clean code concepts, which an excellent discussion of what makes concurrent code difficult to debug and how to clean it up. There is also an appendix that cross references the principles of clean coding with the code transformations made in the last three chapters of the book. This appendix makes the book a great reference to keep on the shelf after reading it.

Overall the book is incredibly helpful, especially to software engineers who are earlier in their career (such as I). Held within the book are many useful techniques that senior engineers have taken a long time to hone, and if you read and absorb the concepts I think everyone can learn something from the book. That being said, several of the concepts that Martin discusses are controversial. His opinion that comments are unnecessary if the code is well organized and named, and in general clean, is definitely something that could be hard to swallow (depending on your stance with commenting). Martin isn’t completely against comments though, just unnecessary comments (he still supports comments in API’s). One of Martins main arguments against comments is that they simply produce one more thing that has to be maintained later on, a valid point. But despite the few controversial ideas that Martin discusses, none of which does he force on you, the book is filled with many highly useful concepts and excellent descriptions of why they are good ideas.

In the end I really only had one major complaint about the book, which is the subtitle “A Handbook of Agile Software Craftsmanship”. It is my opinion that clean code can and should be produced in non-agile environments as well, which I don’t think Martin would disagree with. Clean code is by far easier to modify than unclean code, and so its applicability may be higher within an agile environment, but it is certainly still applicable in non-agile environments (where the requirements are more static). My favorite concept of the book is also in the title, the idea of software engineering as a craft, too much of the time it seems that software engineering is seen as “coding”. The idea that software engineering is just hacking up something that does what your manager asked for is outdated and I think this book gives a nice introduction to software engineering as a true craft that should be treated with care and responsibility. Instead of just writing code, we as software engineers should write code that is of high quality, something that is truly well-crafted.

After reading the book my coding style has changed, I try to write clean code the first time, instead of just getting it to work. I also have a better understanding of why certain coding changes are better than others, which is why I picked up the book in the first place, so it fulfilled my needs and then some. I highly recommend it for anyone that is doing any programming.

Next on the bookshelf is “Data Visualization: Principles and Practice” by Alexandru C. Telea.

Ars Technica recently posted an article on Mozilla’s future version of Firefox.  This version, deemed Namaroka, is the version of the web browser that will be released after Firefox version 3.5, which is currently in beta.  In the article Ars Thechnica talks about the various features of version 3.5 and the upcoming features of the Namaroka release.  As part of the documentation for Namaroka Mozilla has put out a roadmap documenting the various goals and specific features of the release.

Many of the open source software that I keep an eye on include roadmaps in their external development documents, however I have read very little about the idea of creating roadmaps as tools for development. Part of the reason for this may be that what I have read just refers to roadmaps differently, or I haven’t read enough, or possibly that roadmaps counteract the ideas of agile development. Since there seems to be a lack of input on the subject, I thought I would examine some roadmaps and look at their purpose in Software Development.

Songbird’s Roadmap:

If you haven’t been introduced to songbird I highly suggest you check it out, it is an excellent media player built on Mozilla’s software that allows you to both play and store you’re music as well as explore the web in a musical context. They have published roadmap’s up to and after their release of their non-beta software (currently version 1.1), you can find them here: http://wiki.songbirdnest.com/Roadmap. Songbird appears to use their roadmaps as a way of tracking the progress of various large objectives of upcoming releases of their software. They also allow the community to interact with it via comments and the fact that it is in a wiki.

Songbirds roadmap seems to be a resource for the community to see what the development time is being spent on and how far things are coming along. Internally I would assume that it is used in much the same way, a way to track the progress of large objectives as well as pinpointing what the large objectives are.

The Wordpress Roadmap:

You can find Wordpress roadmaps here: http://wordpress.org/about/roadmap/.  Wordpress is an open source blogging platform (I use it for Coding Notes). Wordpress seems to use their roadmaps in a much more specific way than what Mozilla or Songbird does, Wordpress utilizes a ticket system to track the progress of and allow developer involvement in the process of dealing with issues that need to be tackled for certain release “milestones” or versions. As a result there are far more and much more specific items being taken care of on the roadmap, and the entire roadmap as a whole looks much more like an internal document than an external overview of whats going on.

The pro’s of this approach are that the community can get a much more specific view of the changes that are being made, and can perhaps have a more beneficial involvement in the large scale development process. The con is that naturally it is harder to see the overall picture. However by looking at the number of open tickets and closed tickets one can get a very basic picture of the progress (as of this writing for the 2.8 release it stands at: 271 closed tickets out of a total 762 tickets).

Mozilla’s Namaroka Roadmap:

The Namaroka Roadmap can be found here: https://wiki.mozilla.org/Firefox/Namoroka. While Ars Technica calls it a roadmap, Mozilla does not use that name but it is very much the style of a roadmap. Like Songbird’s roadmaps the Namaroka roadmap is a broader overview of the development that needs to take place. However, it differs significantly from the other roadmaps by providing multiple perspectives on what needs to be accomplished for the Namaroka release. What I mean by this is that they have provided multiple sections, a broad overview of goals, a rough timeline of when different items should be completed, and various areas of interest and requirements plus others. This allows for multiple perspectives to be taken on the same things. They don’t provide a way to see what is completed or in progress however, but the document is in a wiki so as the items are accomplished perhaps the document will change. Also like songbird they invite community involvement via a discussion section.

Personal Experience, a basic roadmap from my Senior Project

While I was completing my senior project my team developed a basic roadmap; it was meant mainly as a rough diagram of what needed to be done and a time line of when we could expect things to be finished. However, since we where following a win-win spiral lifecycle model we where working in a risk-driven environment, which meant that whether the timeline said we needed something done or not was purely based on the current biggest risk and not on what the timeline said (however, risk assessment included time constraints). Thus what was really more of our roadmap was our list of current and past risks and their level of significance, this not only showed what we needed to eventually consider but what was currently being dealt with (the highest risk). Unlike the other roadmaps both of these documents where used internally only and where never shown to our “client”. Since our client was also our professor he did see both documents but not as our client, instead as our mentor. Unfortunately, I don’t have a copy of either documents as neither where stored in our CVS.

Final Analysis: where roadmaps fit in agile development

As I stated earlier I think that one of the reasons that roadmaps are not discussed as a part of the development process as much as other documents are is because they tend to orient themselves more toward a waterfall model or non-agile life-cycle. I don’t think that this means that they can’t be used in an agile process, I do think they must be used differently though. So if you are trying to be agile how to roadmaps fit in?

In agile development more of an emphasis is taken on dealing with what needs to be dealt with than dealing with a specific order that common development tasks must be accomplished in. Thus by creating a roadmap it would seem that you are forcing certain tasks to be accomplished in a certain order or direction. As can be seen with the Songbird and Wordpress roadmaps there is not a specific deadline for the tasks other than the over all goal of the version release date, this allows for the various tasks to be accomplished in any order. Also the Namaroka roadmap does not give individual tasks a deadline but instead outlines a very rough idea of when groups of tasks should become “finished” in each various phase of the development. By not giving firm deadlines for specific tasks it is possible to maintain the agility of the development, furthermore, it is always possible to change dates, and by doing this agility can be maintained.

Along with maintaining flexibility in a roadmap they can be great tools in the beginning of a project by outlining a project and preventing developers from diving too deep too fast, and later on they can help developers still see the big picture while developing small sections of code. The key to utilizing a roadmap in an agile development is allowing change within the document, if it stays static and is the absolute rule to the path of development then it is much more like waterfall development and a hindrance to the naturally changing environment of development. However by allowing it to change constantly (like the risks in my senior project) it allows for the whole project’s progress to be visible without hampering agile development.

Furthermore, as all three of the open source roadmap examples shown above are available to the community, it can be seen that roadmaps can also be an excellent way to provide progress reports to the community (or client) of software projects while still maintaining flexibility. Although, depending on the client it may not be a good idea to reveal as detailed an overview of the actual design elements of a software project as these roadmaps provide.

I am very interested in hearing what others think about this topic, or if you know of any articles or books that talk about roadmaps involved in the development process I would like to hear about them.