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.
- 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.
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?
- 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...)