What is your favorite Coding Guidelines Checklist?

Question

What is your favorite Coding Guidelines Checklist?

I don't think one list will satisfy everyone. So the "favorite" part :)

I was about to ask for Embedded programming and C at first. But you can post your favorite in other languages / areas as well.

Answer 1

For PHP, I found the PEAR guidelines useful when setting up my developer team. We based ours strongly on those, and I think many other teams have too.

http://pear.php.net/manual/en/standards.php

Answer 2

For C and C++ (the C subset at least) I find myself following the Linux kernel's CodingStyle document. Mozilla's is good too.

Answer 3

Did anyone find this useful for C++ development?

Answer 4

I think the most important consideration when deciding coding standards is a concencus of opinion within (1) your team and (2) your company.

Most style guides I've seen for any given language are very similar in intent, with a few differences in their recommendations. Usually, these differences are fairly arbitrary.

I used to code embedded C and the company I worked for had an official style guide. It was fairly minimal (similar to http://www.psgd.org/paul/docs/cstyle/cstyle.htm), which I found to be best.

Answer 5

Re: consensus... Yes, everyone has to agree, but usually people will disagree violently on things like brace position, indent style and so on. That is why someone has to make a decision and for it to be fair, using an external existing standard avoids accusations of just choosing your favourite style and enforcing it on everyone else.

Also, by using a widely recognised standard, you improve the chances of the style being portable to other projects or workplaces.

Answer 6

Google has a very decent process for code reviews, supported by their own tools:

• author edits changes in workspace & tests
• author sends email to reviewer
• reviewer views diff
• reviewer sends email back
• possible email discussion
• when reviewer gives it's OK (lgtm) authors submits changes

I wrote more about it in my blog.

Answer 7

G'day,

Go direct to Steve McConnell's book Code Complete 2! Lots of good stuff, with justifications.

Regarding C++, the points Steve raises in his book, plus sticking to the suggestions from Scott Meyer's book "Effective C++" is an excellent start.

HTH.

cheers, Rob

Answer 8

If you're looking at this a code guidelines to form a coding standard, some good places to look are Code Complete by Steve McConnell and the Framework Design Guidelines by Brad Abrams and Kryzstof Cwalina.

Your standard

• should be Consistent
• should encompass all aspects of code construction
• should be different for different languages (not "one size fits all")
• should reflect not only industry adopted best practices but also your comapnies interal best practices
• should be flexible enough to change as technology changes

The end goal is that your standards should be simple enough for the developer to internalize so that it becomes something they don't have to think about while writing code, it just happens naturally. This will not happen overnight, but that's the direction it should take you.

The other thing to keep in mind is that the guidelines can have varying degrees of enforcibility. If you want the standard to cover things like curly brace placement, tab size, etc., you can put that in your standard. At that point, a decision must be made if this is a standard that can not (must not) be broken or one that could be broken but is preferred. This is the famous (or infamous) idea of "picking your battles". Some standards end up being considerably more important than others.

Answer 9

My favorite style for embedded development is a variant of style(9), the OpenBSD kernel style. It's pretty lightweight and imho easy on the eyes.

It doesn't say much about coding practices though, which you might or might not want depending on your team.

Answer 10

There's the Firmware Standards Manual (http://www.ganssle.com/fsm.htm) written by Jack Ganssle which is geared towards embedded software development and programming in C.

We've used it for our embedded systems project and its worked out without any complaints. It goes over file templates, function headers, variables and portability, ISRs, comments, and general coding conventions.

Jack Ganssle is pretty well known in the embedded software community and has a column on embedded.com. He also is a regular speaker in the Embedded Systems Conference (https://www.cmpevents.com/ESCe08/a.asp?option=G&V=3&id=259682) each year.

Answer 11

I like the rules by Juwal Lowy:

The IDesign C# Coding Standard

Answer 12

For Python: PEP8

http://www.python.org/dev/peps/pep-0008/

PEP stands for Python Enhancement Proposal.

Answer 13

For C++ I've found nothing better than C++ Coding Standards by Herb Sutter and Andrei Alexandrescu.

One of the nicest things about this book, is that each standard is about a page in length, which means you can digest the book in very small chunks over time.

Answer 14

I have been using and modifying the Geosoft standards for a while, these are for C++

Answer 15

For PHP, Zend offers a thorough list of guidelines.

Answer 16

The first guideline should be that the list of guidelines should be short enough that you can summarize the list on a single sheet of paper or a single screen in a web browser. If you need to document the reasoning behind guideline, write a reference document for that stuff. Or better yet, make the table of contents enough of a summary that you can just use that as the short list.

I just checked out the Geosoft standards and they aren't bad, but the missing feature is the summary list of the numbered points without the associated explanation text. Its too long.

The guideline from A. Reddy at Sun from May 2000 is pretty good, I think, but really the best part is the last page which gives a really nice summary.

One extra guideline that I like that we are using is:

Do not put $Log:$ in the comment block at the top of the file. We are not using CVS and SVN doesn't honor it.

PS: Sorry about the crazy google link, but I couldn't find the pdf as html anywhere and the last page is the best anyway.

Answer 17

Use a simple process for determining your checklist and change your checklist over time!

Article: How to build a checklist.

Answer 18

Maybe this is a contentious issue, but in my experience, the best/favourite coding standard is the one that all of your developers agree on. You'll likely get religious wars over "mine is better than yours" if you go for any particular developers' standard, an independent standard (such as the ones already suggested in other answers) that gets the most votes from your development team is best.

You can always tweak the chosen standard if it doesn't quite fit.