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.

The R&D team I'm in has decided to adopt a coding standard. We have only recently formed, and have too little code and common coding time of our own to base our standards/conventions document on what has developed organically in our team, and on good examples from our own code etc.

Now, every one of us has some experience from past workplaces - although none of us is at a state of saying "let's adopt this here comprehensive document I have found to be fitting for the kind of work we do here" (*). Plus, some of us (including myself) only have experience from places with no official coding standard, or writing in different languages in a different setting (high-pressure weekly-release production environment as opposed to more research-oriented development work)

So, one of the options I've been thinking about is taking a relatively well-known and well-regarded document, snipping off what we don't care about/care for, and making some modifications based on our preferences.

Is this a common practice? Do you believe this is a good idea? If so, what would be a reasonable 'baseline' coding standard (don't tell me which is best, I don't want to start a religious conflict here; just point out what would be comprehensive or 'neutral' enough to build upon.)

Notes:

  • We are expecting to work with C, C++, OpenCL, CUDA, Python.
  • We are a team of 4 people + manager, expected to grow to about 5-6 within a year or so.
  • In our company, teams are almost entirely autonomous and usually don't interact at all (not even by using each other's code - the work is on entirely different projects); so - no company-wide considerations to make.
  • Regarding tools, at the moment what we know is that we're going to be using Eclipse, so its code formatter is going to be one tool at least. Ctrl+Shift+F has long been my friend
  • When I write Java, I've adopted the practice of adhering as strictly as possible to Bloch's Effective Java. Now, that's not quite a coding standard, but you could call some bricks, cement and mortar for a coding standard. I was thinking of possibly including something like that as part of the 'mix' (minding that we don't do Java).
  • I mean coding standards in the wider sense of the word, e.g. adopting suggestions made in the answers to this P.SE question.
  • I've found a big list of C++ coding standards documents; maybe I should mine that our baseline.
  • (*) That's not quite true, but I don't want to complicate this question with too many specifics.
share|improve this question
8  
Using an externally created coding standard helps reduce holy wars about particular coding styles. –  Steven Burnap Sep 11 '13 at 15:51
3  
What guideline you use doesn't really matter. What matters is that you do use one and that everyone agrees to use the same. That last part is easier to do if you choose a sane one. –  Joachim Sauer Sep 11 '13 at 15:54
3  
Naming conventions are overrated. If you have one module where functions are CamelCase and another where they are snake_case, it's not a big deal if you agree to at least follow the convention already in place for each component. So if the holy war gets too heated, just stop it and leave it inconsistent. –  Jan Hudec Sep 11 '13 at 16:30
1  
I have very little Eclipse experience, but Code standard (not style) enforcer for Eclipse may be helpful –  Dan Pichelman Sep 11 '13 at 16:31
1  
So your choice is use a existing standard or spend the time and money to create one? I don't see a choice here. Go with the free option. –  Ramhound Sep 12 '13 at 15:57

6 Answers 6

up vote 7 down vote accepted

Put another way, you're asking if you should jump-start your team's coding standards by borrowing external standards that you've found. It doesn't sound like anyone on the team has super-strong opinions (yet) on what those standards should be.

Unequivocally, the answer is yes.

An externally sourced standard is superior to nothing. Look at the answers in "Coding standards and coding style, is it that much important?" in order to see some of the advantages for having a standard. Consistency and having a basis to change from are critical from your point of view.

Also have a look at "Handling Coding Standards at Work (I'm not the boss)" as it goes into some of the team dynamics that your team needs to consider when selecting what the standard(s) should be. The team needs to own their coding standard(s) so everyone willingly complies with the restrictions it places upon how each person codes.

You linked to this question, but it's worth pointing out the top answer and its focus on understanding why the requirements are in place. If you use an external standard, it will be hard for your team to understand the basis behind all of those requirements. But if you accept that they are there simply because your team needed something to start with, then it's easy to move on to changing that external standard to something that works better for your team.

Having any standard in place allows your to populate the formatting rules you'll use with your IDE (Eclipse in your case). "Advantages and Disadvantages of Forced Code Reformat" goes into the benefits for everyone on the team for having that consistency with the code they are working on, and gives you the ability to reformat snippets you may borrow from other projects. An added bonus of using an external standard is that it may already be pre-populated in the code formatting portion of your IDE.

Someone on the team will likely complain about a particular portion of the standard and will blame it on the fact that you used an external standard as the base. Have them read over:
- I hate one of our coding standards and it drives me insane, how to process it?
- How do you overcome your own coding biases when handed legacy code?
and then realize they likely would have complained about something within the standard no matter where it came from. Across the number of teams I have worked on, I have yet to see a standard that everyone a) universally liked and b) agreed with every portion of the standard. Reference back to some of the early links to see how to deal with those concerns.


Addendum, you asked about "which one" you should use. I'm specifically not going to answer that as any answer is potentially frought with opinion fueled flame wars. However, you could look at your IDE (Eclipse) and see what options it provides as standard configuration. I'd also search a bit and see if there are any projects that plugin to your IDE and provide additional standards options to pick from. Right or wrong, those standards are already populated for you and can save your team a chunk of work in configuring it for everyone.

share|improve this answer

I'd start with python. Python has coding guidelines that almost every single python programmer out there follows. They are part of official documentation called PEP8.

C/C++ is a huge mess for historical reasons, but since python is not, I'd recommend you follow the python naming convention in C/C++ too for sake of consistency.

Now for C++ it is actually more important to agree on common idioms and make sure that everybody understands reasonable modern C++ style than any wars on naming conventions. You should start with C++ Coding Standards and from online resources make sure to read C++ FAQ.

share|improve this answer
    
Actually I'll believe we'll have different naming conventions for each of C, C++ and Python - at least, w.r.t. things like capitalization, use of underscores etc. MyTypeName is arguably better C++ than my_type_name_t, and the opposite goes for C. But thanks for the references. –  einpoklum Sep 11 '13 at 16:35
    
For C++, you can use the standard used by the STL and boost. Not everybody like it but since you'll most surely use some stl containers it will be consistent with that. –  Laurent Bourgault-Roy Sep 11 '13 at 17:01
    
@einpoklum: For non-types all of C, C++ standard library and Python use "snake_case"; no difference there. The only difference is whether you want to use "MixedCase" for types or also "snake_case". C and C++ library use "snake_case", but otherwise "MixedCase" is very common. –  Jan Hudec Sep 12 '13 at 6:09
    
@einpoklum Use the standard set by the standard library for C++. –  Miles Rout May 13 at 22:03

You can't even discuss this topic without making the distinction between a coding standard and a coding style standard.

A coding standard is a set of rules defining which language mechanisms you are allowed to use, which ones you are not allowed to use, and how to use them. In other words, you define a subset of the language used, and/or a superset, if the coding standard addresses certain non-standard extensions.

A coding style standard is only concerned with cosmetic issues: where to place braces and spaces, how to name identifiers, how to place comments etc.

These two different things might be located in the same document. However, the most serious of the coding standards don't concern themselves with style - the ones I recommend below do not. Most likely because coding style is very subjective and therefore causes a lot of friction when opinions collide.

For C/C++, the coding standards with the best reputation are those of MISRA. They are primary designed for safety/mission-critical applications, but since the key to making programs safer is to remove and avoid bugs, the MISRA standards apply to any programming branch where bugs are not desired.

The standards from CERT are also fairly well-known and more biased towards desktop programming and software security (rather than safety). CERT have standards for C, C++, Java and Perl, and the standards are free of charge.

I would start by looking at MISRA and CERT, rather than some random garage standard found on the web.

share|improve this answer
    
I've never heard about MISRA before, and I don't see that its constituents are overly significant players. Can you explain their reputation? As for the CERT documents, can you clarify whether these are standards for secure programs specifically, or more general standards? –  einpoklum Sep 12 '13 at 18:02
    
@einpoklum To begin with, MISRA-C is used by pretty much every car manufacturer in the world. It is becoming a "de facto" standard for C programming in the whole embedded systems industry, where it is most well-known. Still, there is actually nothing in the MISRA document that prevents it from being used in any form of C program. Both MISRA and CERT are fairly general, they ultimately aim to reduce the number of bugs, bad practice and vulnerabilities in a program. These standards also encourage static code analysis. –  user29079 Sep 13 '13 at 7:48

Using an existing standard as a basis for your own has several advantages. Your code will probably be more similar to external code, making it easier to read/integrate code. Further, if you pick a good standard, it will have been examined by experts who have had good reasons for deciding on their particular rules. As long as nobody on your team is particularly tied to a standard, there is little reason not to use an existing standard as a basis for your own.

If you're not sure which coding standards to use, there are some obvious ideal first choices. In no particular order:
1. Whichever standard is already supported by your IDE. This is probably configurable.
2. Whichever standard is used/recommended by the author of your compiler.
3. Whichever standard is used/recommended by the author of your primary framework (if one exists).
4. Whichever standard is used/recommended by the author(s)/designer(s) of your programming language.
5. Whichever standard is used/recommended by a very large company.

I recommend someone with technical expertise read over whichever standard you are using as a basis for your own standard. A good standard will often have a justification for each rule, which will help you in modifying the standard to best fit your needs.

share|improve this answer

A standard usually helps communication and maintenance. In my opinion, it should be subject to some give and take, especially in small teams, and should evolve. Calling them guidelines may help :-)

Take a look at the Google guidelines for inspiration.

share|improve this answer
4  
It is very subjective which coding guidelines to choose for C/C++. And if there is one I would not choose, it is Google's. They prohibit many things usually considered good modern C++ style by others like boost. –  Jan Hudec Sep 11 '13 at 16:16
1  
How does your answer address the OP's concerns about using an external standard? Suggesting a name change for the coding standards doesn't help the core issues they'll need to address. –  GlenH7 Sep 11 '13 at 17:16
    
@JanHudec I agree. One of things it forbid is use of exceptions. –  BЈовић Sep 11 '13 at 19:47

NO, I wouldn't bother - I think the only benefit would be if your team moved to a place where those standards were used as well, which is not what you want to happen :)

Standards are only there to encourage easier collaboration, so if you know that a #define macro is always in uppercase, then when you see an uppercase identifier in code, you'll have a fair idea its a macro. Similarly, other naming conventions or style conventions will remind you what you're dealing with.

I find standards like file location and name are more useful1 that the code ones (after all, code comes in all shapes and sizes, and you still have to read it) whereas not knowing the readme.txt is in /bin/doc/debug/release/documents is a real pain (as is such a crappy path, but that's another story).

I would recommend you make your own standards up as you go along. That way, you not only get the ones you all like, but you get ones that are definitely suitable for you, your team and the work you do. If you decide that you don;t really care what a while loop looks like, or that case statements must be indented in a certain way, then you're good. If you decide that ++ operators are banned, good too. All your own choice.

You'd have to make it easy to find and update it, a wiki maybe or auto-generated web page from a text description, but otherwise - go for it. Standards have a mythical attitude from some people who are more interested in fanatically following the standard than writing good code, don't be like them - make your own standard that helps you where you need it.

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.