chris clarke

Circles Of Life

Continuous Integration (The way I do it)

Feature Development

Sloppy Code equals Buggy Code ?

Having witnessed a lot of bugs recently, big and small, in some legacy code - there seems to be some patterns emerging. The root causes of the bugs are often found deep inside big classes, often with some suspicious looking commented-out code and the odd TODO floating nearby. Even when implementing new features, I’ve found myself spending most of my time trawling through these larger species of classes trying to work out what they are doing. I find myself deleting chunks of commented out code and tripping over scary looking TODO’s saying things like ‘Fix this when I figure out what it should do’ or ‘Hack - fix me’. These bigger, sloppier classes are minefields for potential bugs and quicksand for productivity.

Having read Ivan and Nat’s attempt at a Real-time Sloppographer, from the Scrapheap Challenge at SPA 2007, I was inspired to come up with a similar utility for measuring Sloppiness in the way it had affected me.

mostLikelyToBeBuggyTop10.py is a quick bit of python I wrote to measure sloppiness based on the things I’ve encountered:

1. size - bigger files get more sloppy points
2. TODOs - more TODOs, more sloppy points
3. does it have a Test? - if not - more sloppy points
4. number of comments - maybe slightly controversial - but the more comments, the more sloppy points - i’ve found files with big chunks of commented out code so it’s useful for me

Sorry, some characters don’t show up, such as ‘+’, but you can get the original here: mostLikelyToBeBuggyTop10.py

Annoying Patterns: Saying what you’re about to do

This pattern is best demonstrated with a few examples:

Basically, the comment is describing what you are doing on the next line, and is just not needed.
Sometimes the comments are telling you something, for example:

Could perhaps be telling you that a method needs to be renamed:

Then the comment can be removed and it is clear what the code is doing.

Origins of Waterfall Software Development

No-one knows the exact origin of the term ‘waterfall’. It was apparently coined when someone looked at a diagram in Dr. Winston Royce’s paper and remarked it resembled a waterfall. In fact the origin of the entire ‘waterfall model’ of software development is very sketchy. It is said to originate from a misunderstanding of the paper Managing the Development of Large Software Systems, written by Dr. Winston Royce in 1970.

Artists Impression of Dr. Winston Royce.

The story goes that somehow Royce’s initial diagram of a process which did not work was adopted as what we now know as the ‘waterfall model’. And was later adopted as a US Department of Defense standard (DOD-STD-2617) in 1985 and shipped across Europe in to Government and Defence projects though NATO.

From what I understand about the waterfall model, and from what I was taught, you proceed through each of the phases once, and each phase must be completed and perfected before moving on to the next. However, reading Royce’s paper, he makes it abundantly clear, on page 2, that this is not a good idea:

The required design changes are likely to be so disruptive that the software requirements upon which the design is based and which provides the rationale for everything are violated. Either the requirements must be modified, or a substantial change in the design is required. In effect the development process has returned to the origin and one can expect up to a 100-percent overrun in schedule and/or costs.

Royce then goes on to present five steps which can help prevent such a thing happening:

1. Complete the coding design before analysis and coding begins - The paper was written in a time when there were a lot of technical constraints, on data size, execution time etc… Royce had found that these things had become problems later on in projects so he introduced this stage before the Analysis stage in an attempt to catch these problems earlier. A program designer would take part in the Analysis phase making the customer aware of storage, timing, and operational constraints.
2. Documentation must be current and complete - Royce was a stickler for documentation - he used it to try and control projects and make sure that they met requirements and interface definitions. One interesting thing he mentions is that programmers should not test their own code and in this respect he saw documentation as a kind of acceptance criteria for how the software should behave - so that a separate team of testers could test the software according to the documentation.
3. Do the job twice if possible - Royce advocated the whole lifecycle process be repeated in miniature at the start of the project in order to:
   

   … quickly sense the trouble spots in the design, model them, model their alternatives, forget the straightforward aspects of the design which aren’t worth studying at this early point, and finally arrive at an error-free program.

4. Testing must be planned, controlled and monitored - The previous three steps were targeted at uncovering as many bugs as possible before hitting the test phase. In this phase, Royce recommends some methods of uncovering more problems including code review.
5. Involve the customer - Royce wanted to involve the customer as much as possible to ensure the software was closer to what the customer wanted however, in his diagrams the customer is mainly involved during design and then at the end of the project.

Having read Royce’s paper, I don’t think the document has been misunderstood as stated from several sources, I think the versions of most projects match quite closely to Royce’s guidelines - plenty of documentation, plenty of analysis and design, strict adherance to specification documents and customer involvement missing at important points. I suspect that even ‘Doing it twice’, which seems like a good idea, has been proposed during a waterfall project, but probably dismissed as a waste of time and money.

I think Royce was trying to improve a software development process which was pretty immature at the time. The most common process which people were using at the time, looked a lot like this:

Royce exposed a lot of the hidden stuff that happened around this, including important practices such as testing. He also had a lot of the right motivation to catch problems earlier and involve the customer more. Although some of his ideas have perhaps been proven to be not so helpful in the long run.