Another thing that we did at Google that I thought was surprisingly effective and useful was strict coding standards.
Before my time at Google, I was sure that coding standards were pointless. I had absolutely no doubt that they were the kind of thing that petty bureaucrats waste time writing and then use to hassle people who are actually productive.
I was seriously wrong.
At Google, I could look at any piece of code, anywhere in Google’s codebase, and I could read it. The fact that I was allowed to do that was pretty unusual in itself. But what was surprising to me was just how much the standardization of style – indents, names, file structures, and comment conventions – made it dramatically easier to look at a piece of unfamiliar code and understand it. This is still surprising to me – because those are all trivial things. They shouldn’t have much impact – but they do. It’s absolutely shocking to realize how much of the time you spend reading code is just looking for the basic syntactic structure!
There’s a suite of common objections to this, all of which I used to believe.
- It wastes time!
- I’m a good coder, and I don’t want to waste time on stupidity. I’m good enough that when I write code, it’s clear and easy to understand. Why should I waste my time on some stupid standard? The answer is: because there is a value in uniformity. As I alluded to earlier – the fact that every piece of code that you look at — whether it was written by you, by one of your closest coworkers, or by someone 11 timezones away — will always demarcate structures in the same way, will always use the same naming conventions – it really, genuinely makes a big difference. You need so much less effort to read code that you haven’t looked at in a while (or at all), because you can immediately recognize the structure.
- I’m an artist!
- This is phrased facetiously, but it does reflect a common complaint. We programmers have a lot of pride in our personal style. The code that I write really does reflect something about me and how my mind works. It’s a reflection of my skill and my creativity. If I’m forced into some stupid standard, it seems like it’s stifling my creativity. The thing is, the important parts of your style, the important reflections of your mind and your creativity aren’t in trivial syntactic things. (If it is, then you’re a pretty crappy programmer.) The standard actually makes it easier for other people to see your creativity – because they can actually see what you’re doing, without being distracted by the unfamiliar syntactic quirks.
- One size fits all actually fits none!
- If you have a coding standard that wasn’t designed specifically for your project, then it’s probably non-optimal for your project. That’s fine. Again, it’s just syntax: non-optimal doesn’t mean bad. The fact that it’s not ideal for your project doesn’t mean that it’s not worth doing. Yeah, sure, it does reduce the magnitude of the benefit for your project, but at the same time, it increases the magnitude of the benefit for the larger organization. In addition, it frequently makes sense to have project-specific code styles. There’s nothing wrong with having a project-specific coding standard. In fact, in my experience, the best thing is to have a very general coding standard for the larger organization, and then project-specific extensions of that for the project-specific idioms and structures.
- I’m too good for that!
- This is actually the most common objection. It’s sort-of a combination of the others, but it gets at an underlying attitude in a direct way. This is the belief on the part of the complainer that they’re a better programmer than whoever wrote the standard, and lowering themselves to following the standard written by the inferior author will reduce the quality of the code. This is, to put it mildly, bullshit. It’s pure arrogance, and it’s ridiculous. The fact of the matter is that no one is so good that any change to their coding style will damage the code. If you can’t write good code to any reasonable coding standard, you’re a crappy programmer.
When you’re coding against a standard, there are inevitably going to be places where you disagree with the standard. There will be places where your personal style is better than the standard. But that doesn’t matter. There will, probably, also be places where the standard is better than your style. But that doesn’t matter easier. As long as the standard isn’t totally ridiculous, the comprehension benefits are significant enough to more than compensate for that.
But what if the coding standard is totally ridiculous?
Well, then, it’s rough to be you: you’re screwed. But that’s not really because of the ridiculous coding standard. It’s because you’re working for idiots. Screwing up a coding standard enough to really prevent good programmers from writing good code is hard. It requires a sort of dedicated, hard-headed stupidity. If you’re working for people who are such idiots that they’d impose a broken coding standard, then they’re going to do plenty of other stupid stuff, too. If you’re working for idiots, you’re pretty much screwed no matter what you do, coding standard or no. (And I don’t mean to suggest that software businesses run by idiots are rare; it’s an unfortunate fact, but there’s no shortage of idiots, and there are plenty of them that have their own businesses.)
Typo alert: “But that doesn’t matter easier” – should be “matter either”.
Coding standards are a great idea, but difficult to carry off.
I think it helps a lot if you stick to stylistic rules. On a committee writing one of these things, the temptation is to start writing a bunch of design rules. This tends to bulk up the document, which makes it harder to follow faithfully. People are likely to ignore a document completely if it is too long to read while they are trying to get things done. The best conventions are those that can be automatically verified with a lint like tool.
Also, documents like this change slowly and through a bureaucratic process. Design decisions embedded in the coding standards can become wrong over time, either because the language changes, or because a new domain is being tackled that needs a different approach.
Style decisions on the other hand can never become wrong because they were arbitrary to begin with.
The other thing that helps, is to build on the coding conventions that come with the language. Python has PEP-8. Java has its own coding conventions. C++ doesn’t have a format standard, but has informal naming conventions from the standard library, and also boost. I think it’s annoying when people start making up a bunch of random inbred rules you would never see in 3rd party code. Microsoft historically was very guilty of this with Hungarian notation in C and C++ code.
You should follow coding standards strictly. But the standards themselves should ideally have enough play to accommodate the odd corner cases that tend to crop up (note “corner cases” – most developers will not encounter them). Two situations come to mind:
* You’re writing odd code – hardware driver code for instance – and need to do stuff like mix C and assembler or things like that. This may call for specific standards for this particular kind of situation. And if the situation is rare in the organization, the path of least resistance may be to let that particular team tweak organizational standards to fit on an ad-hoc basis, then stipulate those tweaks to be official.
* You’re writing code meant to be submitted to an external project. A plugin or added functionality to an external open source project – or a driver for the Linux kernel, to continue the last example. There you may simply need to follow the coding standards of that project rather than your own in-house standards or risk not getting your contribution accepted.
Does Google follow Hungarian Notation as part of the style guide, or is it expressly forbidden? 8^)
Try enforcing style/standards in a graphical programming language!
I’ve been using LabVIEW for over 10 years now, and I’ve seen as many styles as I have programmers in the language.
Like art, I know good LabVIEW programming when I see it.
Code should run from left to right, top to bottom
Sub-VIs should do one thing and one thing only.
Run “clean wires” every so often.
Just off the top of my head. I’m sure that a bit more thought would produce better ones too.
We have a strict coding and code review standard at my company. I found it’s an easier sell for new hires if every rule in the coding standard has a reason behind it (“Follow this rule and you’ll avoid problems X, Y, and Z, and here are the bug reports where those problems cropped up.”)
IM(not so)HO, when I see programmers violating the coding standard it just looks sloppy and makes me wonder what other corners they cut. Good code requires attention to detail. If you can’t pay attention to the coding standard you’re probably missing other stuff. The counter-argument is I’ve only got room in my head for so much detail and if I’m thinking about coding standards, other things will be crowded out. I don’t buy this argument one little bit.
The thing I don’t understand about coding standards (well, the layout and formatting part) is why we still apply them manually. It would be pretty easy to integrate a code reformatting tool into the subversion/git checkin/checkout operation. Not only do you get all that annoying formatting done for free, but (in theory at least) everyone could have their own personal preferred style, and see the entire code base in that style.
But instead we spend time moving curly brackets around.
Coding Standard – comment first then code or code first then comment???
Comment first takes more time.
Code first takes out comment (seldom the time to go back to comment code).
One company I worked for did reviews the wrong way; managers reviewed the code of their underlings. However, the managers couldn’t keep track of what was really going on and their reviews degenerated into a check that the coding standard was complied with. The standard was itself pretty woeful and code that didn’t comply could usually be fixed by running it through indent. But we weren’t allowed to do that. We had to write to the standard and any deviation had to be corrected by hand. Doing it roughly right then spending thirty seconds with indent wasn’t allowed.
Remember the CMM, the Capability Maturity Model, with levels one to five. There was a spoof version with level zero and downwards. This company was bang in the middle of level minus one. It was the first time I ever came across a quality assurance process that was a positive impediment to producing quality software.
Comment or code first?
I use literate programming. This means, pretty much, I write the comments first and the code is written for me. Complying with coding standards is pretty easy when you seldom have more than half a dozen lines of code at a time. When my clients don’t use literate programming I deliver the generated code and the doco. They appreciate the well commented code and the accompanying doco with cross-references from the former to the latter.
One thing about not having any official coding standards is, I can tell just from looking at code written by my Unlucky Predecessors, which of them wrote it. One guy didn’t bother with meaningful variable names: they are all just variations on a theme, or anagrams of one another. And having grown up in the days when every byte counted seem to have given him a pathological aversion to indentation. Then there was the curious case of what looked like neatly-commented, well-written code; which would be interspersed with snippets of spaghetti and then some more neat stuff, only this time in a different, consistent style where it had evidently been copied and pasted from a different source. Yet another didn’t seem to know the point of “double” as opposed to ‘single’ speech marks, so I’d see stuff like
print 'Hello, ' . $name . ' . Nice to meet you!n';And don’t get me started on the person who seems to think ?> and <? are special quotes for embedding HTML into PHP …..
We have a coding standard at work that differs from all the common standards for the language we use. It contains a lot of rules to add unneeded brackets and rules for white-space.
The worst thing is that it gets “improved” all the time, so if you open any reasonably older file you might have to reformat most of it, which not only is annoying but also makes the diffs for code reviews bigger than necessary.
I have nothing against coding styles, but they should be reasonable and should speed up development and not slow it down.
I disagree. The point of coding standards is to make code comprehensible – and it’s often a lot faster to write incomprehensible code. Making code clear – even just on a syntactic level – takes effort, and effort is time.
Coding standards shouldn’t cause time to be wasted on unproductive activities. Updating old code to fit new coding standards definitely qualifies as a huge waste of time.
And for a coding standard to really be valuable, it can’t change often. To reiterate, the point is to make the code easy to comprehend. When the code follows a uniform standard, then developers learn to read that style very quickly. If you keep changing it, that automatic, intuitive parsing doesn’t work.
In my four years at Google, working with four different languages (C++, Java, Python, and a google-specific language called Sawzall), I saw the coding standards changed *once* – and that was a loosening of the standard, so that no existing code needed to be changed to fit the standard. That’s the right way to handle a coding standard. A sub-optimal standard is better than a rapidly changing but closer-to-optimal one.
Very nice to read the code review post and this one.
I’m the chief architect of a product and have been trying to get coding standards in place — before my arrival it was pretty much a free-for-all. Unfortunately, I’ve been fighting against the very excuses you list above. Then there’s “I’m ok with it, as long as you change the standard to fit *my* way of doing things.” Drives me nuts. As you say, you need a standard and it has to be stable.
One of the challenges is the collision between needing to upgrade legacy code and dealing with source code management. A reformat makes it hard to compare versions, since most SCM systems will highlight every difference, not the substantive ones.
I had read of a study done some time ago that showed that a lack of standardization negates the advantage that expertise gives. In the study, they took two sets of developers, one experienced, one not. Then they gave each group some code to analyze and modify. For the standardized code, the experts had a big advantage over the newbies. For the unstandardized code, that advantage went away.
I almost didn’t make it to the end of the article. “Yup, yup, yeah, sure, whatever… ah, THANK you!!!”
The last big project I was on (at an unnamed very large services company) saw me butting heads for two years over the “coding standards” most of which were in place due to an “expert” architect checking all the boxes he could in the style checking tool we used. He later admitted to not even knowing what some of the conditions were about. No matter, he was law.
And no matter that the application architecture itself was disastrously inconsistent. But who needs API or database or messaging consistency when your .java files all have less than 20 imports and every single getter method has full Javadoc?
That experience soured me on standards, something I previously was a supporter of. 🙁
My stance now (in a very much smaller company) is to write as clearly as I can, and to learn to better read less-clear code without worrying about it.
I can *really* attest to how much easier it makes your job when coding standards are applied. In my previous job I was working on some really nightmarish legacy code. Not only were there different bracketing, indenting, and variable-naming schemes used in different places in the project, but also different (all of the above) schemes used in different places in the same *file*.
This project was a big part of the reason that I left the job. I was starting to get ulcers…
My *current* job on the other hand has decent coding standards (some of which are not exactly the same as my “personal” coding standards) and I’ve hit the ground running with the code. I can see which code does what and why. And learning to make minor adjustments to my coding style is a minor price to pay for being able to sleep at nights.
Coming from different professions entirely (military aviation one of them), I’ll inject my perspective here. Many of the concepts in this post, and in MarkCC’s previous one on code reviews, echo lessons that are written in blood in the world of aviation. Decades ago, the “old guard” would have laughed you out of the flight club if you suggested that silly things like checklist discipline, procedural standardization, and crew resource management (i.e., a formal way of saying, “we back each other up and listen to each others’ feedback”) would gradually lead to drastic improvements in safety, efficiency, and efficacy.
They’d offer the same (now-discredited) counter-arguments: I’m an artist. I’m too good for that. It holds me back. I work better on my terms. It’s a waste of time. One size doesn’t fit all.
But as long as you are working in a complex environment, it comes down to “doing things better” in both professions. Can it be a pain in the ass? Sometimes, immensly. But I can integrate efficiently into any other Air Force crew (of my specific airframe) and use the same checklists, procedural styles, and techniques… safely and effectively. I know how to stop something disastrous from happening, when I see it developing, even if I am lower ranking. And it helps us get the mission done when you are facing all manner of stressful deadlines, sleep deprivation, and equipment failures.
I was an amateur programmer back in the day, trying to get my 286 processor to render shadebobs and filled polygons. In my wildest dreams, I fantasized about writing something as complex and ruthlessly efficient as “Second Reality” (the Future Crew demo, not the multi-user universe). All the things MarkCC describes in programming discipline would have sounded ridiculous to me back then! Oh how perspective changes.
Forgive my trip down memory lane… As I see the lessons of professional aviation recapitulated in programming, I wonder what other valuable lessons from programming can benefit other fields.
I have to agree completely with this article. Unmaintainable/unreadable code is worthless code, because even the original author can never be guaranteed to understand their own code X years later. I have found the easiest way to handle code formatting is to have everyone use the same tool that does the formatting for you. That way it’s as simple as hitting the code reformat key/icon and the simple (a.k.a. Time consuming) parts are done for you. This leaves a lot of time to handle the more “difficult” parts of a coding standard.
IMHO Coding standards are the best way for inexperienced programmers to be able to understand what their working on and for experienced programmers to “jump in” quickly and help.
The best way to transition between old and new coding standards is to do nothing but reformatting and submit the essentially original code (with code review) so that only the formatting/standards are being changed. After that then inserting the new changes is easier as the diff will not be cluttered with formatting/standards changes.
The comment around starting strict and then loosening up makes a lot of sense too, because it’s easy to stop checking for things, it’s much more difficult to start.
Oops. Forgot to be explicit. When I mentioned “code reformatting tool” I didn’t mean development tool, only the reformatter. If everyone uses the same too that’s great, but not a requirement.
In my shop we use a tool called Resharper. It is a 3rd party tool that integrates with the IDE. It polices all kinds of coding standards items and also has a ton of great refactoring tools. Its advice has also made me a better programmer.
Although it is customizable, its default settings are excellent.
Pingback: 【外刊IT评论网】为什么谷歌要执行严格的代码编写规范 — 见贤思齐
I once worked somewhere whose Java coding standards outlawed both interfaces and anonymous inner classes. I am not kidding.
The best thing about coding standards is that there are so many to choose from.
I work with python, which is a good language for readability, (and “readability counts” according to The Zen of Python).
In python, there is the PEP0008 coding standard. This is what I try to adhere to. However, it is self-contradictory and open to interpretation.
Several times have I been bashed over the head by people with the question “Have you ever read PEP0008?”. Yes, I’ve read it over and over. What they mean is that they want me to write python code in *their* cherry-picked version of PEP0008.
Perhaps they don’t care about 80 character limits. Perhaps they also want to leave out all single-quotes. Perhaps they have wacky indenting rules.
Who cares? It’s python, the code is still readable so long as people try to get close to the standard. When bosses start bashing their developers for where and how many line endings they put in, and developers spend an extra 10% of their time going over their code to avoid being told off, then the standard has been taken too far. Standard adherence starts to add costs instead of reducing them.
How pointless all this trouble seems when we realise that it is only because programs are still being written as text, to be parsed and re-parsed over and over again, that we have to endure coding standards. If programs were simply saved as graphs of nodes representing calls, statements, procedures etc. then we could reformat the code as suited each developer.
The problem is not the adoption of coding standards, the problem is that we are still writing code as if it were 1970.
“I am a Christan, which provides a good moral system, (and ‘morality is good’ according to great Christians before me).
In Christianity, there is the Bible. This is what I try to adhere to. However, it is self-contradictory and open to interpretation.
Several times have I been bashed over the head by people with the question ‘Have you read the Bible?’. Yes, I’ve read it over and over. What they mean is that they want me to follow *their* cherry-picked version of the Bible.”
Who says coders don’t have religion?
I always liked the statement in the Tcl Style Guide by Ray Johnson:
“I don’t claim that these conventions are the best possible ones, but the exact conventions don’t really make that much difference. The most important thing is that *we all do things the same way*.”
I’m not especially fussy about what the standards are – only that they exist and everyone is required to follow them.
Does it take a bit longer to write code that follows the standards? Maybe, though that will decrease as you learn the standards and Do the Right Thing automatically. But so what? If you’re in that much of a hurry, you are probably doing something wrong. Which takes less time? Doing it right the first time, slowly, or doing it and then doing it over because you wrote in too much haste?
Bravo and thank you. It’s a shame stuff like this has to be repeated over and over, but it does, and you did it well.
_____
Dennis
Well, it is all good unless you have to face reality.
For instance, If solutions like JQuery, that breaks all standards in strict Java Script world and standard programming conventions, became standard. How do you convince me is good to stick to that newly created standard, that is slowing you down 100x times and limiting by this? Shall I stick to this anyway because of popularity and better understanding of code?
I am not the artist, but I see the point why many old school programmers said programming itself is the art. If you don’t agree to that you simply denied evolution and development in IT world, which is essential and driving force of programming itself.
If you’re one person working on a complex project that isn’t using jQuery, then I don’t care what kind of hotshot you are, how brilliant you are, or how much your personal productivity would be improved by using jQuery: if you think that it’s appropriate for you, individually, to decide that everyone now needs to use jQuery, and you’re complaining that a coding standard would hold you back – then you’re an idiot who shouldn’t be allowed within a mile of serious code.
On the other hand, if you’re starting a new project where your team agrees that using jQuery would be a good idea, then you do that. And you update your coding standard for the project to reflect the technologies that you’re going to use for that project.
The point of coding standards isn’t to have some collection of arbitrary rules set in stone for all time. It’s to support the team of people working on a project.
In a team that’s working properly, one person doesn’t decide to go off and use javascript and jQuery for their part of the system, while the rest of the team is writing C++. (I do know people who’ve done that, and yeah, doing it made that one person a lot more productive. But it ended up wasting the time of every other person on the team.) The team decides what language(s) they’re going to use, and what libraries they’re going to use, and what kind of testing they’re going to use, and so on. If you think that that’s unacceptably crimping your style, well… I sure as hell hope I never have to use a system that you worked on.
You clearly didn’t understand my point. I didn’t take a side or judge, just gave an random example and asked a question. And you making assumption, and insulting me on public.
No matter you are individual or working with high industry standards, working in the team and having person witch such attitude is the worst of all. I would rather prefer to work with ‘artist’.
Happy New Year anyway.
I don’t think that you really asked a question. You took a common stupid argument against coding standards, and reformulated it as a question. But even so, I think I answered your “question” quite clearly. You asked:
If you’re working on a project, and you want to use jQuery, but the team consensus was on a standard that didn’t support jQuery, then it doesn’t make a damn bit of difference how productive it would make you, personally. The answer is: yes, you should stick to it anyway – not because of popularity, but because of comprehensibility and standards within the team.
Standards don’t mean that you don’t ever adopt new technology. They don’t mean that you don’t ever change. What they mean is that within a team, you all agree on how you’re going to do things, and then you stick with that until the team agrees to change. So if jQuery comes along, and it would make your team’s work much better, then the team can decide to adopt jQuery, and update their standards to match.
That’s the whole point of things like standards, and code review, and most other good engineering practices. A team needs to agree on how to do things; and then the members of the team need to stick to the agreed upon system. You can’t go off on your own, no matter how much more productive it would make you.
Anyone who can’t understand that isn’t someone whose judgement I want to trust. Arguing that standards mean that all progress and technological change must stop is simply foolishness. And hiding the argument behind a pseudo-question doesn’t change that.
Seriously mate 🙂
I do understand you point and I do agree with you in many aspects. That’s why I felt insulted by you making assumptions who I represent.
English is not even my 2nd language, but what I was trying to point at was this.
You have your pure language of choice no matter which one, c++, java c#, python, whatever.
You have good practices established by inventors and contributors of this very language. You have common design patterns that applies to most of them. If everybody sticks to it all should be clear for anybody within a team.
For a need of particular project some framework can be developed on top of the language as long as team agreed to that and can find it beneficial. And as you said yourself it is a team decision.
My question was:
What if this framework itself has been promoted as a silver bullet solution, broke initial standards of the original language, all design patterns, or actually follows anti patterns but suited well the task and the team. Hell, suited wide range of lazy programmers as well!
After few years due to popularity, laziness of decision makers the rest of the world has been forced to use this newly created framework as a new standard. Forget what you know about language you have learnt. Now use the framework that breaks all the rules and standards you have learnt, adapt.
Is this right? Is this common practice of our state of IT industry is correct?
Because this is happening every day and all I see behind it is purely commercial reason, to promote one solution over another dumping old ones. Legacy code, experience, trained resources, etc. And very often producing over-bloated crap.
I will give you another example by analogy if that makes things clear.
You have English Language, but some folks decided to make a project called ‘new world’ and invented a dialect US English. Quite similar but with some nuances. Both UK and US can understand each other but one side not necessary agrees to what has been done to original language convention.
Now in US there is a bunch of youngsters in state of ‘your favourite goes here’. They decided to use their slang as the common way of communication. Quite weird slang, barely English speaking people can understand them.
But they have been successful with some project and started to forcing the rest of the country to learn their slang because of popularity, everyone talking about it, industry making money on it. So go on! Adopt new standards, forget legacy.
Think about me, I was forced as non English speaker to learn this language because I wanted to be a programmer. And English is widely accepted standard around the word. So I did it, I accepted widely accepted standards.
But if you apply what is happening on the IT world these days is simply trying to create (by analogy again) bunch of slang like languages on top of the English and force others to use it.
Are we creating diversity or Tower of Bable?
Do you see my point now?
Pingback: 为什么谷歌要执行严格的代码编写规范 | HanBud
Pingback: What is a coding style standard? Do style standards really help? Why can't programmers all just use their default style? » No Sleep Til Bootcamp!