Should my team use some common well-regarded coding standard as a basis for its own?

Question

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.

Answer 1

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 "https://softwareengineering.stackexchange.com/q/84203/53019" 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.

Answer 2

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.

Answer 3

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.

Answer 4

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.

Answer 5

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.

Answer 6

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.