Why does Uncle Bob suggest that coding standards shouldn't be written down if you can avoid it?

Question

While I was reading this question, the top voted answer quoted Uncle Bob on coding standards, but I was confused by this tip:

3. Don't write them down if you can avoid it. Rather, let the code be the way the standards are captured.

This bounced in my brain, but I couldn't find a place to stick. If a new person joins the team, or coding standards change, couldn't there be confusion of information?

Why shouldn't I write down a coding standard?

Answer 1

There are a few reasons.

1. Nobody reads documentation.
2. Nobody follows the documentation even if they do read it.
3. Nobody updates the documentation even if they do read it and follow it.
4. Writing a list of practices is much less effective than creating a culture.

Coding standards are not about what people should do, but are about what they actually do. When people deviate from the standards, this should be picked up and changed through a code review process and/or automated tools.

Remember, the whole point of coding standards is to make our lives easier. They're a shortcut for our brain so that we can filter out the necessary stuff from the important stuff. It's much better to create a culture of review to enforce this than it is to formalise it in a document.

Answer 2

There's another interpretation. I don't believe it is what Uncle Bob meant, but it is worth considering.

Don't capture coding standards in a document. Capture it in code, by having an automated process which verifies the standards are being met.

Don't rely on people referencing a document, but at the same time, don't rely on people interpreting the code that already exists and identifying what's convention and what's coincidence.

Incorporate something like Checkstyle into your commit build. This can enforce the basic rules like formatting and naming standards, and then rather than expending mental effort in considering style, that can all be offloaded to a dumb process which is at least guaranteed to be thorough.

If it matters, then define strictly what it is you want, and fail if it's wrong.

Answer 3

People overlook the real purpose of a coding standards document, which is to settle disputes.

Most of the decisions in the coding standard will have only a very minor effect on readability and productivity. Especially if you adopt the 'normal' style for the language, and language designers are starting to realise that this should be part of the spec (e.g. Go).

Because they're so trivial, the arguments can get really heated and run on endlessly, doing real damage to productivity and team cohesion. Or can obscure your change history with endless reformatting between two or more people's preferred styles.

Having a written standard ends the argument. Managers can point at it and deflect dissatisfaction towards the document. You can argue with a piece of paper but it's not going to listen to you.

(See also The Tyranny of Structurelessness)

Answer 4

Because comments are lies.

The coding standard is a great big comment on what the code should be. The code itself is the ultimate source of truth. Truth in this case isn't code behavior, it's the style it's expressed in. If your standards aren't already reflected in your code, you have a lot of work ahead of you.

Uncle Bob sees a comment as personal failure of the programmer, because it proves that he didn’t manage to express the purpose of the code fragment with the programming language itself. Similarly, a standards document is a failure to express a coherent style in the code base.

New programmers should be spending time looking at the code, not spending days reading a multi-chapter standards document (I've had to do this, sigh).

A standards document isn't such a bad idea, but I've been in programming shops where maintaining the standards documents was someone's full time job. Please, if you must keep a standards document, keep it to a page. But if you already have code, shouldn't anyone be able to put together the same document in less than a day?

Having code standards is important. Having a document that dictates what they are is not.

Answer 5

Why does Uncle Bob suggest that coding standards shouldn't be written down if you can avoid it?

If you're asking reasons behind his opinion then you may have an answer only if he will post an answer here (our opinion is just irrelevant), however...

Why shouldn't I write down a Coding Standard?

If you're asking if he is right about it: let me be the only unpopular one (so far) to say that you have no reason to avoid it.

WRITE IT DOWN. However I will try to explain my reasons...

David suggested in a comment that main point of Stephen's answer isn't why you shouldn't write documents but in which form they are. If guidelines are formalized in tools (not merely manual code review) then I may agree (when law does not require something else). Please note that unfortunately tools cannot check everything (theory of computation is not our friend) often because they're limited to a specific translation unit or package or whatever your favorite language call a boundary.

However Uncle Bob's wording does not make me think he is talking about that.

Can I disagree with such senior expert? I do, for almost every point in cited post (see also second part of this answer for details). Let's try to understand why (assuming you already know that coding guidelines are not just about minor formatting issues).

• In some circumstances written coding standards are required by law.
• I do read documentation and I'm sure I'm not alone. Team members may change over time, knowledge can't be in a 5-10 year old codebase or in team members' minds. Organizations should fire people who don't follow internal guidelines.
• Coding standards, once they have been approved, won't change often and if they do you want to know about it. If the standards changed then your documentation (in code) is out of date because all your code does not follow the new standard. Reformatting/refactoring may be slow but you always have a written authoritative guideline to follow.
• It's better to read a 5 page document than to inspect 10/20K LOC to extrapolate a rule (which you may understand wrongly, BTW), no doubt about that.
• It's ironic that someone who wrote many books about design principles and coding style is suggesting that you should not write your own guidelines, isn't then better if he dumped us with some code examples? No, because written guidelines not only tell you what to do but also two other things that code lacks of: what not to do and reasons to do it or not.

"Free self-organizing programming" is good for a ninja 16 year old guy but organizations have other requirements:

• Code quality must be granted (and defined) at company level - it's not something a single team may decide about. They may not even have the skills to decide what's better (how many developers, for example, have all required skills to review MISRA or even merely understand each rule?)
• Members may be moved across different teams: if everyone follows the same coding standards then integration is smooth and less error-prone.
• If a team is self-organizing then the standards will evolve over time when team members change - you will then have a huge codebase that does not follow the current accepted standards.

If you're thinking about people before process then I can only suggest reading about TPS: human beings are a central part of Lean but procedures are highly formalized.

Of course a small organization with just one team may let the team decide the standards to adopt but then it must be written down. Here on Programmers.SE you may read posts by Eric Lippert: I suppose we all agree he is an experienced developer, when he worked for Microsoft he had to adhere to their written guidelines (even if some rules may be wrong, not applicable or useless to him.) What about Jon Skeet? Google guidelines are pretty strict (and many people don't agree with them) but he must adhere to such guidelines. Is it disrespectful to them? No, they probably worked to define and improve such guidelines, a company isn't made by one member (or one team) and each team is not an island.

Examples

• You decided not to use multiple inheritance and nested classes in C++ because you actual team members do not understand it well. Later someone wanting to use multiple inheritence must browse the entire 1M LOC to see if it has ever been used. It's bad because if design decisions aren't documented you have to study whole codebase to understand them. And even then, if it hasn't been used, is that because it's against the coding standard, or is it allowed, but there just weren't any earlier situations where multiple inheritance was a good fit?
• In C# you had overloaded methods to provide default parameters because your code base started when optional parameters were not available in C#. Then you changed and you started to use them (refactoring old code to use them each time you had to modify such functions). Even later you decided that optional parameters are bad and you start to avoid using them. What's the rule your code tells you? It's bad because standard evolves but codebase is slower to evolve and if it's your documentation then you're in trouble.
• Jon moved from team A to team B. Jon has to learn a new standard; while learning he will probably introduce more subtle bugs (or, if lucky, just take a long time to understand the existing code and make code review longer).
• Team A moves to a codebase previously owned by team B. It has completely different coding standards. Rewrite? Adapt? Mix? All of them are equally bad.

---

Uncle Bob

Let them evolve during the first few iterations.

True, until you do not have a standard and your organization assigned you the task to build one.

Let them be team specific instead of company specific.

No, for all the reasons explained above. Even if you think to formalize just code formatting (the least useful thing you may want to formalize) I still have memory of endless (and useless) wars about formatting. I don't want to live them again and again, set it once for all.

Don't write them down if you can avoid it. Rather, let the code be the way the standards are captured.

No, for all the reasons explained above (of course unless you will refactor all your code in one-shot when guidelines change). Do you want to leave your code as-is? How do you inspect codebase to understand current guidelines? Searching by file age and adapting your coding style to source file age?

Don't legislate good design. (e.g. don't tell people not to use goto)

True, guidelines must be short or no one will read them. Do not repeat the obvious.

Make sure everyone knows that the standard is about communication, and nothing else.

Not only, a good standard is about quality unless you want to have a standard only about minor details.

After the first few iterations, get the team together to decide.

See first point and don't forget that a coding standard is usually a process that took many years to be developed and refined: few iterations, maybe with junior developers? Really? Do you want to rely on one senior (if any) member's memory?

Three notes:

• In my opinion drawbacks are more serious with some languages than others, for example in C++ a company level standard is even more needed than in Java.
• This reasoning may not apply entirely (and Uncle Bob reasons may be less extreme) if you're working in a very small company where you have just one small team.
• You're hired (as team) and you will work alone with one new project then you will forget it and move on. In this case you may do not care (but your employer should...)

Answer 6

1. To be useful a coding standard must not talk about matters of substance; only matters of style. It should specify only those things that are arbitrary and ambiguous. e.g. Brace placement, indentation depth, spaces vs tabs, naming conventions, etc.
2. Issues of style are local, not global. Each team should adopt their own peculiar style, matched to their task, and their personality. This keeps the standards simple and light weight. Corporate standards become overburdened with all the possible considerations, configurations, and exceptions.
3. Within a team, the only reason to write a separate coding style document is if the code produced by the team does not meet the standard. In which case you have no standard. To be effective, the standard should be expressed by the code itself. And if that is so, there is no need for a separate document.
4. In legacy systems teams and styles change over time. There's nothing wrong with that. Old code will have older style. Newer code will have newer style. The team should be aware of the styles, and their ages. Whenever new code is written, it should be in the new style, no matter where in the code it is located.

Answer 7

Why shouldn't I write down a Coding Standard?

There are many reasons for this. Here are some considerations:

1. How much time are people spending "learning" code standards only to have lots of time go into the entire team reviewing, discussing, documenting, revising... etc. code standards. This is like constantly discussing your "Employee Handbook" - how often does that make it on the agenda of a team meeting??

2. When a project gets defunded/shelved/etc. then the few people that remain usually cannot continue to adhere to (or maybe have not even read) the standards. The next thing you know, all that effort to "keep the code clean" was pretty much wasted anyway.

3. If the project stalls or a new lead is brought in, it's very likely that person will totally ignore the previous rules and want to do it a new way. Again, what was gained by codifying standards??

You should be sure to read #6:

After the first few iterations, get the team together to decide.

In other words, when it's time to start a project, just go with the flow for a while. Then discuss the general rules of coding standards the current team is using - and basically follow them. That way, you maximize the effort that goes into improving the product while minimizing the effort needed to write, review and document the "syntactic sugar" that went into getting executable code.

Very few teams derive huge benefits from coding standards. Usually, "readability" is far too vague - and most developers don't greatly benefit from exact rules on spacing, new lines, etc. but you can avoid constantly annoying developers by having at least a few rules.

Answer 8

Another answer that I don't think has been stated clearly enough, is that it also means that people don't follow the rules blindly. It means that people have to come up with actual justifications for their design decisions and coding conventions, rather than just depending on the the fact that it has been written down to justify it.

Answer 9

Firstly, as far as I know, Uncle Bob is a Java person, this is very important for understanding what he says.

When working in a Java or C# team, if the current code has been written by experienced developers, it's easy for me to pick up the coding style and keep up with it. If I am not willing to do so, maybe I was not the right person for the job... If there are no code reviewing or pair programming to pick me up when I don't keep to the style, then the company has a larger problem than the way I name member fields!

Both Java and C#, along with most modern languages, have been defined so that there are few "simple" traps for a programmer to fall into.

However when I started programming I was using C (and later C++). In C you can write code like

if (a = 3);
{
   /* spend a long time debugging this */
}

The compiler will not give an error, and that's hard to spot when reading over lots of code. However, if you write:

if (3 = a)
{
   /* looks odd, but makes sense */
}

The compiler gives an error, and i's easy to change the code to 3 == a. Likewise, if the coding standard does not allow = to be used within an if condition or "empty if statement", then a code checker can be used as part of the build system to track this error.

My views on coding standards changed greatly when I moved away from C/C++: I used to like coding standards that were strictly enforced, and many pages long. I now think you only need to list the tools being used, and get informal agreement between the original team members on a few naming conventions. We no longer live in a world of teams of over 30 developers writing applications in C/C++...

There is a reason I never liked JScript, and think TypeScript is the best thing to happen to web development for years. I expect that Web UI developers still need coding standards due to the defects in the design of HTML/CSS/JScript etc.

Answer 10

Having the source be the self-documenting coding standard implies two things.

1. People must consult the code base and review it in order to become proficient contributors. This is incredibly important. Reading coding guidelines is a waste of time compared to diving into the code base.
2. It concedes that minor differences are unimportant. It's important to agree upon and understand the basic principles. Maintaining a consistent style is not pursued as l'art pour l'art. It does not allow uncreative nitpickers to annoy and distract other people. It is about facilitating communication through code in a team.

Answer 11

A frequently updated and well written code standards document can be very useful, but usually this is not the case. The standards document does not reflect the actual coding standards used by the company since it is very difficult to create a good standards document and even more difficult to keep it up to date.

Instead of having a poor and misleading coding standards document, it is better to have none and let the code itself represent those standards. Either way the most important part is to apply the standards in the code, and this requires much more than just a document. Motivation, processes, trainings, tools etc are much more important.

Answer 12

A very important thing that hasn't been stated clearly enough is that coding standards are like language: they evolve. A written coding standard stands in the way of this, and if it doesn't it's continuously outdated and useless.

Not having a nailed down coding standard isn't that bad. If you do peer reviews on check-in, whenever something that isn't compliant with the coding standard enters the repository that means 2 people thought about it* and decided the benefit of this variation outweighs the inconsistency with the rest of the code.

Not having a written down standard also removes red tape that would prevent a team of a company to try a new variation of the coding standard for a new project, either because they want to try out something, or maybe because a different standard has practical applications on some of the automated tools they use.

Writing down a standard has a tendency to remove more flexibility than was originally intended, while also taking up quite a bit of time which could be spent doing other things. I'm not saying you shouldn't ever write coding standards down, written standards certainly have their benefits, especially if teams working in different locations work on the same code base.

Strongly related: Evolution in coding standards, how do you deal with them?

---

*If people don't think while peer reviewing code on check-in, your problems are much bigger than just coding standards.

Answer 13

Changing them becomes a major hurdle, and people will adhere safely to the letter of the law rather than engage brains and do the right thing.

There will come a day when part of the standard is unhelpful, and makes the code worse. Some people will adhere to the standard, because it's written down and they're safe, and because rules are there to be followed. People who want to write good code rather than standard-compliant code will be frustrated and angry. There will be arguments and disagreements, whereas if the standard wasn't written down, there would be exploration and discussion.

Answer 14

I think many posts here are confusing coding standard with style guide.

Making sure that modules developed by different teams have the same compiler options and ABI is a different kind of thing from how many spaces are indented.

Things like the proper way to structure #include files and not polluting the global namespace in a header file should be documented so they can be used as a checklist during initial coding and code reviews.

In particular "don't use XXX because it causes compatibility problems with YYY" isn't something you would see by example in following other code, since it's not there. So let the code be the way the standards are captured might be unclear or utterly missing for some kinds of standards, and thus this cannot be a universal plan.

Something seriously pervasive and important like not using exceptions or not using new in certain embedded systems cannot be simply left to be common culture knowledge, as that "information is cultural (only)" contradicts the fundamental principles of manufacturing standards like ISO-9000, that the developer of these embedded systems is using (e.g. for automotive applications). These important things must be documented, signed off on, and filed away in a formal way.

But that applies to coding, not to style.

The inventers of C and C++ show, by example, the use of lower case names and not CaMelCaSe. So why do so many developers not follow the implicit example from the fount? Shouldn't the style of the standard library and the canonical teaching materials be the implcit style to follow?

Meanwhile, people do follow the example of the standard library headers for things that should not be copied, like the use of __Ugly names for macro parameters and the include file non-repeat pattern.

So having stuff is often not seen as important style, or conversely having examples may not be clear as to what should not be followed in project code. Both are counterexamples to the thesis that "style"(or coding conventions) is best left implicit.