The Three "R"s of Clean Code

Establishing Code Quality Standards

Mandate via Manual

A client of LeanDog was looking for a way to introduce code quality standards to their development teams. There had been a few meetings prior to LeanDog's involvement. The prevalent line of thinking was to draft a standards manual for dissemination to the teams. This would consist of a comprehensive set of rules and clear specifications to which all teams need comply.

There was a good deal of discussion around people's historic failure to read and follow this type of documentation. Such failure to comply mandated policing. There were a number of possible solutions; training, financial incentives, managerial targets, code reviews, code audits, and code compliance tools.
Ummm, yeah. Don't do that. Ok?
Keep it as simple as possible. Assume the people you work with are competent, capable, and want to do their jobs well. Developers tend to take personal pride in their work, as do most people. I've yet to meet anyone in the field who proudly (and seriously) proclaims, "I do my job poorly."

This kind of governance should not be necessary. If it is necessary, then remember that your people are competent, capable, and want to do their jobs well. Failure to meet a standard says more about the standard than the people.

It is likely the problem is the manner of communication and enforcement.

Voice via Vignette

Rather than a tome of requirements or a blanket statement such as, "Follow the standards in Clean Code.", give the team simple guidelines that they can agree to and internalize. Short, simple reminders of what quality is to the team. With these simple reminders, they have a catalyst that fires the synapse that brings back all the other "rules".

Enter the Three "R"s of Clean Code

For this particular client, LeanDog helped to establish a set of three simple reminders; Readable, Reliable, and Responsible. These may not be the right reminders for your team. Work together to find what resonates with you.

We restricted ourselves to a single sheet of 8.5"x11" paper and documented the standards we felt were most important. Once the page was filled, we reduced it by eliminating duplicates and highly similar items. We then sorted it in priority order and cut it to half of a page. We then studied the list and came up with groupings. We moved items into the groups and discussed how it all "felt". It took only a couple of iterations to finalize the list.

The team now has four signs that hang in their work space. The three Rs and The Boy Scout Rule Each of the R signs has a short list that further describes what the team means by the "rule".

Readable

Descriptive Function Names
Small Functions
Few Comments
Few Arguments

Reliable

Tested
Descriptive Function Names
Necessary Code

Responsible

Single Responsibility Principle
Necessary Code
Tested

Less is More

We did not cover many things. We don't talk about specific conventions for naming. We don't cover formatting items such as indentation or where the curly-brackets belong. We focused on a select few things that the team felt would guide them toward better overall code. These signs hang up around the work space as regular, simple reminders. And the entire team not only knows what these mean, they follow them without any governance beyond integrity and a commitment to the team.

What would be on your list?

As I said, the list was developed by the team for the team. Maybe there is something you think is very important that was overlooked. Think on this for a while and then let us know what your personal (or team) list would look like.

4 comments:

  1. Very nice!
    Why is "Descriptive Function Names" there twice?
    I'd replace it in the "Reliable" section with
    "Maintenance Free". That focuses programmers to really finish things and not to push unnecessary work over to the operations team.

    ReplyDelete
  2. ClancyBirrell12/07/2010 5:45 PM

    The boy scout rule is fantastic and so simple, I like and will be using it and espousing it at every opportunity.
    Having said that however, it is subjective and heavily dependent on the prime assumption of competency.
    Great list.

    ReplyDelete
  3. anything that helps people remember gets my thumbs up.

    Got to be careful though; condensing information runs the risk of generalisation, too much information is lost leading the reader to assumptions.

    Have you ever used mind maps? These are pretty good for summarising things like this in an 'easy to recall' format while keeping associations between them.

    ReplyDelete
  4. A set of nice easy rules like this will work, but I think there're still a few more steps, such as training and code reviews. Training in what the steps mean. One person's idea of readable might be to write such concise code it's illegible. So, training which is the pre-stage and code-review is the post stage are vital.

    Think about it from the point of view of a new team member coming in, what resources are there for that person to sit down and understand what it mean to write neat code.

    ReplyDelete