Agile Zone is brought to you in partnership with:

Michael Norton (doc) is Director of Engineering for Groupon in Chicago, IL. Michael's experience covers a wide range of development topics. Michael declares expertise in no single language or methodology and is immediately suspicious of anyone who declares such expertise. Michael is a DZone MVB and is not an employee of DZone and has posted 41 posts at DZone. You can read more from them at their website. View Full User Profile

The Three "R"s of Clean Code

12.03.2010
| 11746 views |
  • submit to reddit

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.
References
Published at DZone with permission of Michael Norton, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Alexandru Repede replied on Fri, 2010/12/03 - 8:30am

no code duplication

Michael Fortin replied on Fri, 2010/12/03 - 2:16pm

I'd apply those same principles not only to code, but package design, and project layout. Monolithic poorly names projects and packages become difficult to maintain as well.

Thomas Mueller replied on Sat, 2010/12/04 - 6:33am

I would value "keep it as simple (and short) as possible" over "very small functions". Having an algorithm in one function with 90 lines may be easier to read and follow than 20 function with 6 lines each. Keep it simple also means no duplicate code.

Some Java developers use go overboard with "final" and "this.". Eclipse has a feature to automatically add those everywhere. Such code is very verbose, making it hard to read. Also, adding Javadocs to getters and setter doesn't make sense if the Javadocs doesn't contain any additional info (setName: sets the name).

Mark Haniford replied on Mon, 2010/12/06 - 12:34pm in response to: Michael Fortin

Michael.  I agree with you.  That seems to be a subject that isn't covered that much.

Jason Kilgrow replied on Fri, 2010/12/10 - 10:37am in response to: Alexandru Repede

@Alexandru: "Necessary Code" under the "Responsible" area

Emma Watson replied on Fri, 2012/03/30 - 3:11am

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.

java program

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.