Establishing Code Quality Standards
Mandate via Manual
A client was looking for a way to introduce code quality standards to their development teams. There had been a few meetings prior to our 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, I 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 workspace 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.