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:

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?

Hmm. I'm trying to imagine how this would work in a large multinational company with hundreds of developers and a code base spanning decades. — Matthew James Briggs, May 24 '16 at 05:02
@MatthewJamesBriggs: it works as least as good as a written-down standard most of the devs ignore, or which had a different content at the time when the code was written initially. — Doc Brown, May 24 '16 at 06:09
@MatthewJamesBriggs: agreed. The style guide should contain enough information to recognise previous conventions that are now deprecated, otherwise the culture of "copy the existing style" will find some 10-year-old horror to resurrect. Also, when cliques accidentally form that use different and incompatible specimens for deducing the official style, the written style guide says which of them is right (or ideally, prevents the clique forming in the first place). And if some of your hundreds of devs don't read docs, in a large company you can just fire them for gross muppetry. — Steve Jessop, May 24 '16 at 08:50
Although to be fair, Bob also said you shouldn't have a company-wide coding standard in the first place, written or unwritten. Rather, each team/clique should develop its own. — Steve Jessop, May 24 '16 at 09:07
Instead of writing a document that no one will read, use a linter that enforces code to be a certain way. If it's part of your development process, it's unavoidable. — Seiyria, May 24 '16 at 12:45
@MatthewJamesBriggs Well, it's all about the culture. As long as you can keep the culture alive, it's going to carry over all of this "automagically". If you can't, the standards will likely be considered outdated and useless anyway. The real problem is when project management is so poor that people leave too fast to keep the culture, and no standards will help you then. — Luaan, May 24 '16 at 14:21
@everyone I've been on the stackoverflow since January 2009 and never seen this "uncle bob" tag. Can someone explain what this "uncle bob" thing is (preferably by editing the "uncle bob" tag)? — Trevor Boyd Smith, May 24 '16 at 14:42
To understand that comment from Uncle Bob, one must have a more broad understanding of that philosophy. Code should be "Self Documenting". It should read almost like a book. Commenting will ALMOST ALWAYS be left the way it is even after someone makes a change, leading to misunderstandings and code rot. Also, the Boy-scout Rule. Every time code is touched, always make it better. With these concepts (and others) in mind, his rule(s)/guidelines make sense. — Jeff.Clark, May 24 '16 at 17:39
@Jeff Why? If I don't know the coding style I will have to spend lots of time reverse engineering all the details by looking at existing code. Before I've spent that investment my "improve everything I touch" will practically just make the code worse and inconsistent. — Voo, May 24 '16 at 19:53
@Voo The point is that the code should read like a novel already, and that every time you touch your code, ask yourself things like, "Do these variable names make sense", or "with my additions is this function now too long--should split this function up into two functions?" Yes, if you are new to a company, you may not know if they use all caps for constants, but that is something you will need to look at and learn no matter what. When you figure that out, you can add that knowledge to your Boyscout rule repertoire. — Jeff.Clark, May 24 '16 at 20:16
@Seiyria What would you suggest for more "high level" practices such as "how do we represent events in this code?" and "how should modules that use locking expose the API?" — Owen, May 24 '16 at 22:16
@MatthewJamesBriggs - I work at that company, and I can describe it in one word: Badly. — Bob Jarvis - Слава Україні, May 25 '16 at 03:19
@Jeff Whether variable names make sense or if a function is too long has little to do with a coding guide though (that's a generic enough to be obvious anyhow). The interesting things are "How do we do dependency injection in this code base?", "how are tests organized?" and so on. Nothing you can just divine without spending quite some time looking at the code. Now if it's neither an old nor large project that's fine. But a 15 year old multi million LOC application will have changed over time and it's impossible to update all existing code every time you learn how to do things better. — Voo, May 25 '16 at 05:53
(Yes that would be nice, but is just infeasible). Hence you'll also have to look at the right parts of the code to figure out the current standards. Particularly if you have young developers, this won't be trivial for them. On the other hand giving them a few pages to read together with some high level overview over the different parts will be pretty helpful to get started. — Voo, May 25 '16 at 05:57
I don't see code styles as different from other common company practices, like dress codes or parking regulations. If you want them followed you need to develop a culture of conforming to expectations and you need to write them down. Granted, even if you do both of those things people might ignore the rules, but if you only do one or zero of them then there will definitely be significant groups of people ignoring the rules. I'm not sure how big a group can be before it's useful to write down the important decisions you've made, but speaking for myself I think 1 might be too big to skip that. — Steve Jessop, May 25 '16 at 09:49
Figure out how to encode them in the formatter for the IDE used for the team, and ensure everybody use them when formatting. — Thorbjørn Ravn Andersen, May 27 '16 at 08:15
@SteveJessop - I think the difference between code styles and dress codes are that there are tools that make conformance easier. Sonar and CheckStyle are the way to address this stuff now-a-days. So Uncle Bob's comment probably has to be taken in light of the fact that "writing them down" is still kind of pointless (nobody cares or reads them), but implementing them into your build pipeline is not pointless. The cultural aspect that Uncle Bob's seeking is handled in how the team prunes the rules in the tool. So really, the whole argument is kind of an anachronism these days. — Calphool, May 28 '16 at 17:44
Why that obsession with your uncle? I'm not really interested in your family affairs. You have been posting about your uncle whatshisname repeatedly. — gnasher729, Feb 28 '18 at 08:07

score 259 · Accepted Answer · answered May 24 '16 at 04:34

259

There are a few reasons.

Nobody reads documentation.
Nobody follows the documentation even if they do read it.
Nobody updates the documentation even if they do read it and follow it.
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.

answered May 24 '16 at 04:34

Stephen

8,848
3
30
43

4

Comments are not for extended discussion; this conversation has been moved to chat. – maple_shaft May 24 '16 at 14:41
12

And if you want to enforce things, you should have a build process step that enforces it, not a style guide that does. – Wayne Werner May 24 '16 at 18:35
34

Do you really not have a standard document, but just yell at people for the first few weeks at every code review? This seems like you'd basically expect beginners to reverse engineer your coding style guides. Or is this more a hypothetical "I think that's what he meant"? Now if this is about automatic tools enforcing those rules - agreed, that's essential. But I don't want to have to laboriously figure out the rules. – Voo May 24 '16 at 19:44
13

@Voo, why do you feel you need to yell during a code review if an issue comes up? – Jaap May 24 '16 at 20:39
2
If they're not written down anywhere, rules pedants can't point out that your code hasn't technically been following the standards for months and should all be revised even though it's working fine.

aroth

May 25 '16 at 04:24

20

@Jaap I thought the hyperbole was obvious.. apparently not. No not yelling at people, but telling them that they have to go back and fix all the things they violated because they couldn't know better. – Voo May 25 '16 at 05:49

5

@Voo: you don’t need to “reverse engineer coding style guides”. The conventions should be apparent when looking at the existing code. Everything which doesn’t immediately jump into the eye is either, uncommon or not even fixed. In case there are really important rules about something rarely occurring, it might be worth discussing it with the new developers, when they are the ones who have to write such code. Communication can’t be overestimated. – Holger May 25 '16 at 12:14

1

@Voo I love having my code reviewed. It forces me to write better code and justify my decisions to someone who is viewing it without prejudice. I've never been yelled at or even aggressively attacked during a code review. – Stephen May 26 '16 at 00:32

1

@maple_shaft has already moved long conversations to chat once. does he have to do it again? – Insane May 30 '16 at 02:45

score 116 · Answer 2 · answered May 24 '16 at 06:50

116

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.

answered May 24 '16 at 06:50

Tom Johnson

1,039

6

Actually, I suspect that something like this was at least part of Uncle Bob's reasoning for the suggestion. Automation of coding standards goes alongside automated testing as a useful way of improving quality, and I'm sure that Bob knows that... – Jules May 24 '16 at 13:02
11

It might be worth mentioning rule #6: After the first few iterations, get the team together to decide. With just rule #3 it seems like he's advocating no coding standard, but when considering all of the rules together, and most of all #6, it seems like he's really saying: "Don't force a coding standard at first. Let it develop organically, and after a while sit down with your team to hammer out the details." Which is very different from "Don't formalize your coding standard" (which seems to be the essence of a lot of answers). – Shaz May 24 '16 at 18:45
If you read the items I think you will find that this is certainly not what he meant, for instance this one alone should tell you something: 2. Let them be team specific instead of company specific. – Bill K May 24 '16 at 20:10
Note that I'm answering the question "Why shouldn't I write down a coding standard" - not "What did Uncle Bob mean". That may run counter to the title of the question, but not its spirit. – Tom Johnson May 26 '16 at 06:51
Note that an automated coding format system that doesn't provide an escape clause (where I can turn it off for a section of code) is almost certainly going to be malware at some point. – Yakk May 26 '16 at 17:24
That's a fairly standard feature though. At least, all the tools I've used in the Java ecosystem support local suppressions. – Tom Johnson May 26 '16 at 17:37

score 70 · Answer 3 · answered May 24 '16 at 09:23

70

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)

answered May 24 '16 at 09:23

pjc50

13,377
1
31
35

20

This is incredibly important for teams dealing with legacy code. Especially when going from code following one set of standards (or not following any standards) to another. Without a guideline to refer to, it's impossible to tell which code style to follow when there are multiple styles already present in the codebase.
I think the advice to not write standards down is meant for very small teams working on greenfield projects without risk turnover - a very rare case, in my experience.
– thomij May 24 '16 at 14:42
5

It's much more important to agree to a standard, than the actual contents of the standard. You can get used to just about any style if you work with it long enough. – Mark Ransom May 24 '16 at 22:04
3

Arguing about trivialities is a sign of incompetence, IMHO. Settling the concrete dispute will not fix the underlying problem. – Jørgen Fogh May 25 '16 at 13:05
1

Yes, dispute resolution and keeping the change history unpolluted are both huge, especially when you have a mix of OCD and not-so-OCD developers on your team. However, I've found written standards to be far less effective arbiters than automated tools like StyleCop, which lay down the law without making it personal or wasting managers' time. – Eric Hirst May 25 '16 at 19:03
12

"Arguing about trivialities is a sign of incompetence" - I wish this was true in software engineering... I'm afraid some very, very competent (at least technically) devs are exactly the people most fond of arguing about trivialities. Hell, it's their national sport. "Infinite are the arguments of mages" -Ursula Le Guin – Spike0xff May 25 '16 at 19:10
With legacy code, if you are adding two lines to an ancient piece of source, having a style checker reject the whole file is going to be mightily depressing. At least if there's an agreed standard document you know how to write your twopence worth, even if the rest of it is horrible. – Alfred Armstrong May 27 '16 at 16:36

score 21 · Answer 4 · edited May 24 '16 at 10:29

21

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.

edited May 24 '16 at 10:29

TRiG

1,172

answered May 24 '16 at 04:42

candied_orange

108,538

22

I've actually experienced the multi-decade-old codebase with the "no comments" policy; while it does encourage very long descriptive method names, it's absolutely terrible at capturing intent, reasons not to do things, and we only get away with it by having one of the original authors still with us. – pjc50 May 24 '16 at 09:17
We're a MS shop, so for stylistic things, like naming, we point to their guidelines. For everything else (the stuff that actually matters), we have a one page document.Ooutsource it if you can. ++ good answer. – RubberDuck May 24 '16 at 13:51
7

+1 "Having code standards is important. Having a document that dictates what they are is not." Well and succinctly put. – David May 24 '16 at 14:19
@pjc50 Well, that doesn't really mean much. I'm working with multi-decade-old codebases that have comments... and it doesn't help one bit. The main problem is always the same - everything looks obvious to you. Even something you just spent two weeks researching, because your brain now understands and pretends it's trivial. Can comments be useful? Yes! Are your comments useful? Only someone else can really judge that. Descriptive methods aren't the only thing you replace comments with. You still need documentation, and you need to keep it alive. – Luaan May 24 '16 at 14:29
4

@pjc50 I've never heard Uncle Bob encourage a no comment policy. He doesn't teach that you should never comment. He teaches that you should feel bad when you find you have to do it to be understood. Uncommented unreadable < commented unreadable < readable code that doesn't need comments. Notice that the comments you mention are ones that are completely decoupled to HOW the code works. Standards documents can turn into a brain dead check list that gets ticked off in a code review. What's important isn't that you get all your ticks. It's that the people at the table understand your code. – candied_orange May 24 '16 at 17:43
@pjc50 That seems to me as just another symptom (similar to commenting) of the same problem--Code not being written well enough to be self documenting, AND not following the Boyscout rule. A system evolves over time, and so must the code. I like CandiedOrange's comment above, it captures the intent well. – Jeff.Clark May 24 '16 at 17:46
3

"New programmers should be spending time looking at the code, not spending days reading a multi-chapter standards document". No idea what coding guides you follow, but Google's C++ style guide can easily be read in under one hour and is much easier to figure out than having to reverse engineer the preferred style based on existing code (which sounds plain horrible to me). The same is true for every other style guide I've ever read. – Voo May 24 '16 at 19:47
5

@CandiedOrange: Often, the most useful comments are the ones that describe the reason certain things weren't done [since in the absence of such comments, future programmers may waste time trying to implement and later retract seemingly-obvious "improvements" that turn out to be unworkable]. Unless one goes really crazy with variable names, there's no way even the most brilliantly readable code can capture that information. – supercat May 24 '16 at 22:09
1

@Voo If you're spending time "reverse engineering" a style guide from code you're falling into the same trap of thinking the documentation is more important than the practice. The idea is to look at the old code before you write new code so that what you create doesn't look like weird code. The fancy term for this is the principle of least astonishment. Don't surprise me with code without a darn good reason. Any standards document is only a means to this end. Nothing more. – candied_orange May 24 '16 at 22:20
1

@Candied What's the largest, oldest project you've ever worked on? Because I'm somewhat sure it couldn't have been particularly old or large. No 15 year old project is still using the same guidelines as when it started (hopefully at least). Which means different parts of the code will have different approaches to things as how to approach dependency injection, what to do with exceptions (particularly c++) and so on. Now the naive view is to "every time you figure out how to do something better just rewrite everything else to follow that standard".. good luck with changing a few million LOC. – Voo May 25 '16 at 05:48
@Voo the largest, oldest project I've ever worked on had spec's that were born before I was. Included phone numbers of people to contact if you had questions who were long dead. This is from the age of manual typewriters. So yeah. Old. When I say the style guide was chapters long I'm not kidding. It needed multiple binders. The way we dealt with it was to look at the most recent contributions to the code base and conform to them. It's not that hard a problem to solve. – candied_orange May 25 '16 at 08:42
1

@Candied That's not a style guide. Not sure what several multiple binders are, but if you look at the usual open source style guides and how to contribute documents, that can easily be put into 10 A4 pages and read easily in an hour (check out google's c++ style guide for the basics and then imagine adding project specifics to it). But you make my point: – Voo May 25 '16 at 09:27
2

Instead of reading a few pages, you had to figure out which the newest part of the application was (that's not the same as "last place that was changed" - you have to adapt old code too and will adhere to the surrounding parts there) and then reverse engineer what exactly was just an accident by some other new guy and what was actually intended. And that's not talking about the much more interesting higher level things than "do we use pascal case or not?". Those will take more than 10 minutes to figure out. – Voo May 25 '16 at 09:30
@Voo it was our code standards. And it amounted to a style guide. And people learned most of what they needed to know by just finding a recent contribution to the code base by a senior developer and imitating that. Despite us being expected to care about the style guide most didn't and did fine. We learned what was really cared about in code reviews. The style guide existed for no better reason than that it was supposed to exist. I've worked in other shops with no guide. Followed the same imitation technique. Again, was just fine. A guide can help. But don't think you can't live without it. – candied_orange May 25 '16 at 10:53
I'd actually love to hear about the landscape of a company that pays a person full time to maintain a coding standards document. – David van Dugteren Jun 07 '16 at 23:40
@DavidvanDugteren It was life critical software. ~20 programmers supported by ~40 individuals doing things from configuration management to testing to operations. It was waterfall through and through. Had some good points. Had a number of bad. Biggest problem was it was old and did many things in an old way. Very resistant to modernisation. Yet it was thought of as the new system because it was replacing an older system that was still in use. Parts we're still being converted to the "new". – candied_orange Jun 08 '16 at 07:23
Well that sure sounds a little silly. The best people to maintain a coding standards document are...well...in my experience... the umm.. coders. – David van Dugteren Jul 21 '16 at 03:59
@DavidvanDugteren well officially they were coders. But they were the sort of coders that gravitate to spending most of their time in microsoft word. – candied_orange Jul 21 '16 at 04:21

score 18 · Answer 5 · edited Apr 12 '17 at 07:31

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

I've downvoted this because I feel the answer is off-topic to the question, which is why wouldn't you (and specifically Uncle Bob) write a coding standard, not why you should. I think everyone understands the plus points of having a written standard, but the downsides are harder to determine and when a respsected industry senior comes out with a position opposing the usual practice in the industry, examining why is certainly a worthwhile thing to do. — Jules, May 24 '16 at 13:06
@Jules unfortunately your vote and other votes down that may come because of the reason you point to will be obscured by "sympathy upvotes" from hordes of lemmings attracted to this question from hot network list at sidebar. They have no idea about site quality norms and they don't care, they only want to be entertained by "various opinions" and this "answer" serves them well — gnat, May 24 '16 at 13:13
@Jules I agree site quality must be kept high and if it's off-topic I'll be happy to remove it. However can you point to which part of the question is asking to discuss about Uncle Bob's opinion? Isn't, in that case, just opinion based and then off-topic (unless Uncle Bob will directly answer here)? Isn't the main point of the question the bold part (I repeat for simplicity: Why shouldn't I write down a Coding Standard?) — Adriano Repetti, May 24 '16 at 13:44
Unless (correct me, I may be wrong about site rules) if I ask "why should I do X?" then only answers that tell me reasons to do it are on-topic (even if "to do X" is absolutely and evidently wrong). @gnat you're also welcome to clarify site rules. When a respected industry senior comes out with his own opinion, probably he should also explain it otherwise we just speculate (isn't then off-topic?) — Adriano Repetti, May 24 '16 at 13:55
your answer merely exploits slippery wording of the question. Title says it pretty clearly "Why does Uncle Bob suggest that coding standards..." and asker probably assumed that answerers will read the question in this context. But oh well, enjoy lemming upvotes, there will be plenty since question is at #2 in HNQ now — gnat, May 24 '16 at 14:05
@gnat thank you, I don't need upvotes for off-topic posts, isn't "Why Mr X did Y?" off-topic in this case? We don't know his reasons and he didn't explain them, shouldn't be question closed as off-topic then? How would you answer to this question? Inventing random reasons or saying the premise is wrong? — Adriano Repetti, May 24 '16 at 14:13
@AdrianoRepetti - Uncle Bob has done a lot of explaining over the years, so it is reasonable to consider someone may have some insight into his way of thinking, but you are correct if Uncle Bob's direct interpretation is required. — JeffO, May 24 '16 at 14:45
@jeff yes, if question is about "why he thinks so" then answer is just a guess. If question is "is it right?" then my personal answer is d*** absolutely no. — Adriano Repetti, May 24 '16 at 17:03
I'm confused by some of your examples. The first seems to be opposed to coding standards entirely by suggesting that checking if your code follows them is a tedious task and waste of time. The second seems like it's a suggestion that changing standards is bad, and you should stick with what you started with, regardless of how the language changes. — 8bittree, May 24 '16 at 19:28
"unless Uncle Bob will directly answer here" ... stranger things have happened. — Jules, May 24 '16 at 20:52
@jules I hope he will! There are 1000 things I'd ask him about his books! — Adriano Repetti, May 24 '16 at 20:54
@gnat I think Jules has just been nice. Down-voting with a comment is a constructive action. — Alessandro Teruzzi, May 26 '16 at 14:19
...your organization assigned you the task to build one. Isn't that a specific example of Uncle Bob's qualifier "...if you can avoid it"? Once assigned, it's no longer avoidable. — user2338816, May 30 '16 at 06:12
@user2338816 yes, of course you can't avoid an assigned task however the point is "...let them evolve during first few iterations...". You have not to update coding guidelines (...unless your company asked for...), it doesn't matter if you then write it down or it's inherited through oral transmission from senior team member to newly initiated ones. To be serious, what I mean is that usually it's not your duty because it's shared across multiple teams (of course if they share same language). — Adriano Repetti, May 30 '16 at 06:58
"when he worked for Microsoft he had to adhere to their written guidelines" -- you bet I did. And of course we made use of FXCop and StyleCop to prevent some bad patterns from ever getting checked in. — Eric Lippert, Jun 23 '16 at 16:41

score 12 · Answer 6 · answered May 27 '16 at 07:56

12

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

answered May 27 '16 at 07:56

Robert Martin

1,161
9
6

I have few perplexities: 1) to be useful a coding standard shouldn't talk only about formatting (matter of holy wars but easy to understand reading code) but constructs to avoid, coding patterns (to prevent common mistakes, not easy to understand language features) and security issues. These are coding guidelines (more useful than formatting issues). 2) Given the premise of point 1 then it's not about personality (but it may be about tasks), you can have a lightweight corporate standard, it's your own duty to make it lightweight. – Adriano Repetti May 30 '16 at 08:55
3) Code may tell you what to do but it can't convey what you should not do (unless you want to study whole code base and even in that case...just didn't happen to have to use X construct or it's a no-no?) Another important thing is the reasoning: why not? and why yes? Things may change over time but how you know if initial premises are still valid? 4) and when you're a new team member and you write new code...do you study code base with same age to keep that coding style? The day after you move to another newer component and you study codebase again (filtering by creation date?) – Adriano Repetti May 30 '16 at 09:00
BTW if, instead, you suggest to do not write down only code formatting styles then I may agree (well, actually not but with not so strong reasons besides memories of endless and useless discussions that will inevitably arise each time - and which a corporate guideline will avoid once for all) however you should make it clear or people will interpret your words too literally (see most of answers + comments here). Also that point about "goto" is little bit misleading in this sense (IMO) – Adriano Repetti May 30 '16 at 10:39

score 4 · Answer 7 · answered May 24 '16 at 06:47

Why shouldn't I write down a Coding Standard?

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

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

Aster · Answer 8 · 2016-05-24T10:57:35.667

4

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.

edited May 24 '16 at 10:57

answered May 24 '16 at 09:25

Aster

157

score 4 · Answer 9 · edited May 25 '16 at 08:13

4

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.

edited May 25 '16 at 08:13

Marc.2377

375

answered May 24 '16 at 12:13

Ian

4,603

4

"The compiler will not give an error" most modern C and C++ compilers support reporting such behavior with warnings or, if desired, full errors. https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html – JAB May 24 '16 at 14:30
2

"Firstly as far as I know Uncle Bob is a Java person, this is very important in understanding what he says", that's no true, Uncle Bob has written fantastic articles on C++ and he definitely has worked several years with C too. – Alessandro Teruzzi May 24 '16 at 14:42
@JAB, Thankfully C/C++ stopped being used for new "business applications" a long time ago, (e.g. before modem C/C++ compilers), and is now mostly only used by C/C++ experts, rather then people that are UI experts (MFC) for example. – Ian May 24 '16 at 15:40
Did you mean "Javascript" instead of JScript" at the end of your answer? – Marc.2377 May 25 '16 at 10:45
such a kind of error ( = instead of ==) should be catch by unit test anyway in any language. – Alessandro Teruzzi May 25 '16 at 12:42
@AlessandroTeruzzi, most coding standards predate "test driven development" by a long time. Also a lot of "system code" is hard to unit test with repeatable tests, so debugging a failing test still takes time. – Ian May 25 '16 at 12:54
1

@AlessandroTeruzzi A unit test will tell you that a method is failing. Why it is failing is a different matter - even if you had unit tests for a method with that kind of code, you would have a really hard time trying to find out what's going wrong. C++ is one of the most punishing languages to debug. – T. Sar May 25 '16 at 19:17
2

I think there is a misunderstanding here, you cannot take a single sentence of UncleBob and analyze it in isolation. If you have SOLID software with small classes, short method and bulletproof unit test coverage the coding standard is redundant. If you have weak code, huge interface, big functions and little coverage, the coding standard can give you some benefit. But, UncleBob is not suggesting to do not have one, but to spread it verbally with collaboration and refactoring (remove weak code from the source base). Make your code the living coding standard. – Alessandro Teruzzi May 26 '16 at 09:09

Peter - Reinstate Monica · Answer 10 · 2016-05-24T15:14:38.237

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

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

score 2 · Answer 11 · answered May 24 '16 at 06:25

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.

score 2 · Answer 12 · edited Apr 12 '17 at 07:31

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.

score 1 · Answer 13 · edited May 29 '16 at 22:56

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.

score 0 · Answer 14 · answered May 28 '16 at 04:23

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.

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

14 Answers14

Examples

Uncle Bob