Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I recently saw that Microsoft released a coding standards document (All-In-One Code Framework Coding Standards) and it got me thinking... The company that I work for has no formal coding standards at all. There are only a few developers and we have been together long enough to have evolved into similar styles and its never been an issue.

Does the company you work for have a documented coding standards? If no, why not? Does having a standard make a difference? Is it worth writing a standard from scratch or should you adopt another standard as your own (ie. make Microsoft's standards yours)?

share|improve this question

10 Answers 10

up vote 24 down vote accepted

It's important for a team to have a single coding standard for each language to avoid several problems:

  • A lack of standards can make your code unreadable.
  • Disagreement over standards can cause check-in wars between developers.
  • Seeing different standards in the same class can be extremely irritating.

I'm a big fan of what Uncle Bob has to say about standards:

  1. Let them evolve during the first few iterations.
  2. Let them be team specific instead of company specific.
  3. Don't write them down if you can avoid it. Rather, let the code be the way the standards are captured.
  4. Don't legislate good design. (e.g. don't tell people not to use goto)
  5. Make sure everyone knows that the standard is about communication, and nothing else.
  6. After the first few iterations, get the team together to decide.
share|improve this answer
1  
+1 for quoting Uncle Bob. and +1 (if I could) for the suggestion of NOT writing them down. –  Walter Sep 8 '10 at 15:20
11  
Why no writing them down? –  Fishtoaster Sep 8 '10 at 15:45
4  
@Fishtoaster - The idea is that the code itself documents the standard. Just as design documentation is often not maintained as the code changes, detailed coding standards documents will get out of sync with the code as the standards evolve. What we do is choose some representative modules and use them as guidelines. It's worth writing a brief introductory document (we use a wiki and link to the actual code) that shows you where to find the representative code. –  Paddyslacker Sep 8 '10 at 15:50
    
Ok, the code-documents-the-standard makes sense if you assume the standard is often evolving. That raises the question of why your standard's evolving, though. The biggest reason I can think of to have a coding standard is consistency, which you don't get if the standard evolves. –  Fishtoaster Sep 8 '10 at 16:50
    
If the standard is owned by the team, then the team should be able to evolve the standard over time. If not, you'll end up with either the standard being one person's idea, or with some of the archaic suggestions that are currently being documented in this question: programmers.stackexchange.com/questions/1338/… –  Paddyslacker Sep 8 '10 at 17:24

I think it's essential to have a coding standard, even if all it says is "we use 3-space indentation and open-brackets go on the next line." A few benefits:

  • It makes reading through the whole code-base much easier, since switching between coding styles between files is annoying.
  • It makes reading a single file easier, since any file updated by two developers with conflicting styles will eventually tend to get those styles mixed. Reading through a file that mixes tabs and spaces (and editing it later) is a pain in the ass.
  • It makes it easier for new developers to use good style if there's an explicit standard, rather than an implied one.
  • Consistent naming conventions make it much easier to find functions/variables. Was it ArraySort or array_Sort or sortTheArray or doSortArray or...?

In terms of whether to adopt an existing standard, it doesn't really matter- consistency is what's important. If your developers have a dozen different styles, you might as well pick an existing, published one. If you've all evolved into a pretty consistent style, just write that down and use it.

share|improve this answer

My former employer has a coding standard. I'm considering formally documenting one for myself, as well.

Or, as you suggest, finding a decent existing standard and modifying/adopting that. For a company, I would certainly suggest that they look at existing coding standards, but create/modify one for their own particular needs. There isn't necessarily a need to create one from scratch, but some care should be taken to make sure that the coding standard makes sense for the type of software the company creates.

Yes, having a coding standard makes a difference, but it isn't a silver bullet. Code is more legible as there aren't as many different style clashing and some common mistakes/pitfalls can be avoided. Even with a standard you'll have some variation in coding styles, but that variability will be reduced. The goal isn't to try avoid all variation or prepare for every possible situation. Too complicated a coding standard can be worse than none at all.

share|improve this answer

I disagree with the "we are an X shop" so we format our code in all languages in the same way.

Personally I have found that most languages have different accepted styles.

I really cant stand when C programmers write Java code with C formatting. Not only does it not look like Java, but it fools them into thinking they can use other C-like practices in Java.

I think that if you have a standard it should be per language

share|improve this answer
    
+1. My Objective-C doesn't look at ALL like my PHP. –  Dan Ray Aug 22 '11 at 12:37

Coding Standard discussions come down to this:

  • Yes you need them, consistency and clean code is a cornerstone of good development.
  • What they are almost doesn't matter, so long as everyone follows the same standards.
  • Don't write your own, you're end up in an endless and painful discussion. There are plenty out there that are popular.
  • Using public standards (like those on MSDN) gives you an agnostic 3rd party that can't be argued with. If you want to argue with them, refer to point 2.

If you're developing in C# in Visual Studio, then StyleCop is a silver bullet. If you're also using ReSharper, then the StyleCop for ReSharper plugin is just awesome.

share|improve this answer

Unfortunately not. So everyone has its own way to use spacing, indentation, and so on, everything mixed (this way we don't even have to use the "blame" function to know who is the author of a line of code!)

But, even worst, someone writes variable and class names in Italian, someone else in English...

I always adapt my style to that of the language, library and framework I'm using, so that a source code looks uniform and plain.

share|improve this answer
3  
Ouch, I never even considered multiple languages...that's got to be difficult. –  Walter Sep 8 '10 at 15:16

Keep in mind that this is a coding standards document which is specific to the All-In-One Code Framework.

I have worked at various companies, some of which had an existing standard and some (most) of which I helped develop the standard. For the most part, if you are doing .NET based development (and even if you're not, most of the rules still apply) you should take a look at the Framework Design Guidelines. While this is specific to writing public facing APIs, most of the guidelines apply equally well to any code.

The biggest concern with code standards is to keep it relatively simple and straightforward. You want developers to be able to internalize the guidelines presented, so giving them a 50+ page document is useless. You can still create that document if you want to provide background, examples, etc. but you will also want something that boils down to a set of bulletted guidelines. Your coding standard also has to be a flexibile, living document that needs to change as technology changes.

share|improve this answer
1  
Yes, I understand that the document I referenced is specific to the All-In-One Coding Framework, but it's the genesis for the question that came out of reading it. –  Walter Sep 8 '10 at 15:18

We're a blub shop, so we use the blub programming conventions.

Now Paul Graham and friends are much smarter than us, but us blub programmers, we can all read each others blub, in fact, any blub programmer can read our blub code.

In fact, because of the design of blub, any blub programmer can read any single blub file and understand it, because blub hasn't got a macro system.

If we program in say, C or C++ (we're all multilingual, even though we program in blub) we use mostly blub style for new code, or for open source stuff, the standard of the project we're working in.

share|improve this answer

You need one standard. I've seen different standards in different corners of an application that had different leads that all wanted to do it "their way". Perhaps the concept of "standard" was misunderstood. Very insane. And, the worst standards are generated by one person. Doesn't matter who that person is, if one person alone develops the standard, it's almost assured to be a bad one.

share|improve this answer

It can help people, it can also really helps with tools:

If you want to be able to use any sort of automatic code formatting you really need to standardize the rules it is going to use, else you will constantly be getting a lot of meaningless formatting changes cluttering up your diffs.

Default rules sets for static analysis tools may well check for a specific naming style, and its probably easier all round to conform to that then write a bunch of new rules. (unless you are going to just turn the rule off altogether)

lastly its good to standardize anything which needs to be consulted with someone outside your team. i.e. you probably want a standard copyright notice in your headers as you don't want to be running every new file you write past your companies legal team, and you certainly want to get the names of any public API right first time

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.