Recently I was doing a code review, and I stated that the person who was responsible for writing the code should remove the comments. They are too obvious I stated. The person was amazed that I was suggesting something which was the opposite of the encouraged software engineering “best practices”.

I proceeded to explain my philosophy on comments, and after a long and drawn out debate I think they came around. My philosophy goes like this. There are three types of comments:

1. The Good

These comments explain the reasoning behind your ideas at the time you wrote the code. They are the WHY comments. “We considered doing X but rejected it because of Y.” The because of Y is very important. In fact, that is what makes this a Why comment. We considered doing X but rejected it is a what comment and should be removed. If the reason Y (pun intended) can be called into question, then the code can be changed possibly for the better.

2. The Bad

As I hinted to above these are the WHAT comments. As an example “This loop checks each value in the array to see if it matches the given criteria”. Good naming should render this comment completely unnecessary. OK, but why take it out? Surely it isn’t hurting anything? No not right now, but it can easily get out of sync with the code, and end up confusing the heck out of somebody. Whereas if the variables are named correctly there is no need to explain what you have done, as it will be obvious by reading the code. If it is not obvious then simply refactor it into a method that explains what it is doing. For example the code that the comment described above could actually be factored into a method named CheckArrayForCriteria. Then it is obvious to everyone and there is no way the comment can later be rendered obsolete (and confusing) by a refactoring. Beside the fact that they can lie, there is another thing that I don’t like about what comments. They actually hinder your ability to read code. The eye is drawn to them, instead of the code itself. They also mess up what I call the visual locality of reference. They break up the code part above the comment from the code part below the comment, and if you read the comment, it may be difficult to remember the top part when considering the bottom part.

3. The Ugly

These are the bad comments that are sometimes a necessity if you are delivering an API to a third party. You don’t really want to write them, and more times than not they don’t add any value, but they are required and you can’t do a thing about it. These are the Javadoc or C# Xml (triple slash) comments. Yuck – they are hideous to look at, and completely destroy the visual locality of reference, but what can you do?

For the first time in my career I find myself writing contracts. After doing a little research about the traditional types of contracts, they seem to be inherently anti-agile, which goes against my way of thinking. After doing more research I found one type of contract which seems especially suited to my agile beliefs, but I realize that most businesses won’t understand why I write contracts this way. I am writing this blog entry in order to justify the peculiar type of contracts I write.

There are essentially two types of traditional contracts: fixed price and time and materials (also called labor and materials). Let me discuss these one at a time.

Fixed price contracts are where the product and the payment are agreed-upon before starting the project, and the compensation is paid regardless of the actual costs.

Fixed price contracts are risky for both parties. The business can end up paying way more than they should, and the software development firm can end up not getting paid for a significant period of time. For example, if something unforeseen goes wrong, the software developers could be working for months at the end of the project with no pay at all. In the other direction, the software team could convince the business that the project is going to take a long time to complete, either maliciously or unintentionally. Then, during the course of development the software engineers may find something which enables them to finish the project in a couple of weeks (e.g. open source code which does the bulk of the work) and sit on the project until the due date. Software developers have to pad or buffer the estimate to protect themselves against unforeseen circumstances, but if nothing goes wrong the project may complete early, once again causing the business to pay more than it should have.

In addition to the risk of paying too much money, or not getting paid enough, depending on your perspective, fixed price contracts have the potential to be used against either party so that neither party gets what they want. I call this hiding behind the contract. The developers want to get paid, but businesses can insist that they meant something else by the wording in the contract, and refuse to pay until what they were thinking is achieved. On the other hand developers can delivery shoddy software which “meets the requirements”, if no mention was made in the contract of quality, maintainability, stability, etc.

From a business point of view fixed price contracts are also difficult to manage. In fact they are more like gambling than management. In real life managers would never give their teams a contract and tell them to go build the software without allowing for frequent reviews to gauge progress and make adjustments. So if businesses wouldn’t act this way for their own teams why would they allow teams outside of their organization to act this way?

Fixed price implies one more thing which is bad for businesses: fixed goal. Often during the course of creating software, during a review for example, there is a flash of insight on the part of the business, and a resulting decision to move the product in a slightly different direction than originally specified. This direction is often more marketable, more user friendly, or simply meets the needs in a way that the originally specified product couldn’t. But if it takes more time to implement then obviously the developers are going to have a problem with spending more time for the same amount of money. Similarly on the software side, once some parts of the software are completed it can shed light onto other parts of the software, and result in drastic changes to the estimates. Instead in order to obtain a good software estimate, a lot of energy needs to be expended up front that can not be billed. This effort doesn’t result in any work towards the actual software, again a loss for both parties.

Hopefully I have convinced you that fixed priced contracts have a lot of drawbacks.

The second major type of contract is a time and materials type of contract. This type of contract basically states that the business will pay the software developers for the amount of work that they do until the project is completed. Time and materials contracts are only dangerous for the business, because the software developers are guaranteed to get paid for the amount of work they are doing even if it isn’t furthering the project in any way. However, a lot of businesses won’t accept time and materials contracts, for this very reason. Ultimately software development companies who restrict themselves to writing these contracts may lose a lot of business.

As I was contemplating this I remembered reading in Agile Software Development Ecosystems by Jim Highsmith, about another type of contract that fits into the agile philosophy a little better. In the world of rapidly changing requirements, the type of contract that makes the most sense is an iterative one, where each iteration gives the business a chance to give feedback to make the product better, and choose which features to implement next. The problems with the fixed price contract are that they are unchangeable and don’t require or allow for this sort of frequent contract revision with the customer. The problem with time and materials contracts is that they don’t tie the work software developers are doing to particular features in the product or hold them accountable for getting “real” work done.

Highsmith mentions a fixed schedule variable scope contract called a delivered feature contract. This style of contract states as long as there is work to be done, and the business is happy with the work delivered the project continues. There are two important points to this type of contract. The first is that there must be periodic reviews setup, to make sure that the software developers are making the business happy. The second is that there needs to be a prioritized list of features that the business needs developed which is the work to be done. If initially the business thinks that it requires a huge number of features, but as the project progresses they realize that they can ship with a smaller subset, the project will be over as soon as the subset is delivered. At the periodic reviews the company can critique the software delivered thus far, potentially correcting issues early on that would have huge ramifications later in the project. They also get to decide together what to work on next, so that if the business has an idea to change the product after the contract has been signed it can be done.

Delivered feature contracts also protect the software developer by paying for the work done on a feature, not a fixed price per feature. With that said, the most obvious question is how does the business know how to budget for a delivered feature contract, since there is no fixed price? In other words how does it protect the business against the problems of the time and materials contract? If written correctly estimates can be included so that they have some idea of how much money the project will cost. In addition the project can be terminated after any iteration, allowing the company who chose the wrong software development firm to get out early.

This blog entry draws upon the works and talks of many members of the agile movement including but not limited to Jim Highsmith, Robert Martin, Kent Beck and Scott Ambler.

In order to produce agile software there are really two components that have to stay agile: the people and the code (which is ultimately the product).  If either one doesn’t stay agile the other one is doomed.  If the people don’t stay agile then there is no motivation to change the code.  If the code is not agile then it doesn’t matter how much the people want to change it – it is very difficult.  Both are required for an agile software company.

How do we go about making sure that our people stay agile?  The more time they are able to think (and code), the more agile they become.  Developers work best “in the zone.”  It takes about 10-15 minutes of uninterrupted time to get there.  One way to keep interruptions from occurring is to hold fewer meetings.  There are three fundamental practices that should be instilled in all called meetings.

1. Identify the required people and include an agenda in the invite.
2. If those required people are not present within 5 minutes of the meeting’s start time, cancel the meeting.
3. Finally, the person who called the meeting should always summarize the meeting appropriately.  They should also somehow publish the notes and/or action items from the meeting (Sharepoint? in the bug tracking system?).

If that seems like a lot of work, it is.  That’s really the point.  Because you shouldn’t interrupt people’s valuable time without a clear important goal.  If it is worth calling a meeting, it is worth doing it right.  If that serves to deter the number of people that call meetings, then that is a positive side effect.

Another great way to keep people agile is by pairing them together, and encouraging them to discuss possible solutions to complicated problems.  Pairing has a number of benefits involving skills transfer as well as offering two different viewpoints on the problem.

Agile people have versatile skill sets.  They are generalists.  They work hard to learn new skills and apply those skills until they end up with multiple specialties.  Over time of course a skill might be forgotten, but they could pick it up if need be .  One of the best ways to encourage this is by rotating people throughout the department.  Instead of keeping your web developers and your database engineers segregated and fixed, shake them up!  Training and conferences also help give people versatile skill sets.  Basically trained people make less mistakes.

How can we keep the code agile?  Agile code is healthy code.  It is easy to change.  Unit tests are the best way that you can assure that your code is healthy, and refactoring is the best way to assure that your code is easy to change.  When you have good well-trained people working on code making lots of changes, it becomes easier and easier to change over time.  As you have new people or poorly trained people working on the code it tends to get more and more difficult to change or fragile over time.  As people are able to take their time and make sure they do the job right (have only 2-3 things to deal with at any given time) the code tends to improve, and as people are harried by deadlines and release dates they tend to do a poorer job.  Peer reviews can also help balance this effect.  The person peer reviewing the change has nothing on their plate right now except for looking at this code.  If they do a poor job and let lots of stuff go, it might affect the other things they have on their plate later.  If they do an excellent job, it’s not going to take that much longer than the poor review, and there is a positive impact to future tasks.  So they are motivated to make sure they catch items and get them addressed.

I think one of the key things to push for is a lightweight framework that always makes sure that developers are doing the right thing.  Any rule worth stating is worth enforcing.  Also, program managers should be setting aside time to make sure that their code base is agile enough to support the changes that are bound to take place.  To keep the code agile you need a person or in the case of a ton of code maybe even a group of people that go around looking for ways to eliminate code and make it simpler.  This person(s) can spend their time trolling through the code looking for inefficiencies and areas to make common.  Over time this will pay off in a sub-linear rather than exponential increase in complexity.

There are numerous agile methodologies: Scrum, XP, Lean, Crystal, DSDM, etc.  And they all agree on 4 fundamental things.  They prefer:

• individuals and interactions to process and tools
• working software to documentation
• customer collaboration to contract negotiation
• responding to change to following a plan.

While there is value in the ones on the right, the ones on the left are more important.

It is especially hard to be agile at an FDA regulated company.  Sometimes I think they prefer the ones on the right.  In fact in a couple of cases I am sure of it.  I know they value documentation over working software, because documentation has yet to harm anyone (other than perhaps the person writing it .  I also think that they prefer processes to people, and following a plan rather than responding to change for the same reasons.  And although the software won’t kill anyone, it is not likely to be usable by anyone either .

Despite the differences in opinion there are ways to make it work.  Often this involves defining a plan that allows for change and using easier and lighter weight methods of documenting – like pictures and videos.

The ultimate goal of a good employee should be to put themselves out of a job.  It seems counterintuitive, but it is true.  I mean every single employee from the janitor to the CEO.  The truly great CEOs understand this.  But even the janitors – if they could find away to make the floors perpetually clean, think of what an accomplishment that would be!  The only feasible way they could do this is through some form of automation.

We as developers should strive for the same thing.  You should strive to do such a great job, to write such good code, that does exactly what it is supposed to do, is so easily understood, easy to maintain and add features, that the people that hired you to do the job in the first place won’t need you anymore.  I say this knowing that there is no way they will let you go.  Instead what will happen is that you will be promoted and given new responsibilities to automate.

As a manager you also should be striving to make things run themselves.  One of the best ways to do this is schedule time to develop automation.

Those of you who know me understand how strongly I feel about this subject.  There is just too much work to do manually.  The more software products you develop the more you have to maintain.  But the goal is obviously to build as many profitable products as possible, and they obviously need to be maintained to some degree.  So where does that leave you?  If you had to leave part of your staff on every product that you have ever developed you would end up with huge bloated teams where communication is a nightmare.  So automation is really the only answer.  This is a huge part of agility, making it easier to do common tasks.

So like the Robert Heinlein short story about the man who was too lazy too fail – anywhere that you see an opportunity for automation, take it.  I think a fundamental part of the responsibility of any member of a software team is questioning why you do something.  Part of this is asking yourself if there is an easier way than the way being suggested, one that requires less overall work.

Often that easier way will be automating some repetitive task.