Recommended C++ and Java Coding Standards?

Gerard J. Pinzone queries: "My company is looking to implement C/C++ and Java coding standards. However, I can't seem to find a definitive list. I'm more familiar with Java and have suggested that we use 'Elements of Java Style' and Sun's documentation. BTW, beware of 'Netscape's Software Coding Standards Guide for Java.' It's woefully out-of-date! Any suggestions?"

Comments

Try this

[pong]

Coding Conventions

C++ standards

[Kirruth]

For C++, Stroustroup's home page offers a solid set of advice and links:

http://www.research.att.com/~bs/C++.html

Since he designed the language, I guess he is authoritative.

If portability is important or if you are likely to Open Source some of your code, Mozilla offers a great style guide for this:

http://www.mozilla.org/hacking/portable-cpp.html

C++ compilers are still contrary beasts, and it is worth being aware of the pitfalls.

A number of the tips, especially the "do's" come from Scott Meyers "Effective C++" series, which has to be recommended for anyone looking to define a common company approach to C++ programming.

for java may I recommend..

[zonk the purposeful]

Use the pretty printer

It reformats your code (i use it via ANT)

Just play with the settings and see what you like, it'll reformat the code to what you want.

I just set it up here, and it works a treat.
Saves all those source code arguments about where the squigaly brackets go.

Heh

[kitts]

This is a definite must read.

Things to think about

[cjhuitt]

I helped develop our coding standard at work, although it is still somewhat a work in progress. Bear in mind that this is all for C/C++, but a lot of it may carry over into Java.

I don't think you need to be reminded of the reasons for having a coding style standard, but in case anyone questions it, it undoubtly increases readability of people's code, and reduces the time needed to understand other people's code. We have also found that we are slightly better organized in how we produce code when we follow these guidelines.

Some suggested things to think about:

• Naming Conventions? Be sure to have all functions named the same way, regarding capitals, underscores, and that sort of thing. The same with variables, macros, and whatever else you can think of.
  
  For example, you might say all begining capitals for functions, such as "void OnOKButtonClicked()", first lower case then all starting caps for variables, such as "fltNewGradePercentage", and all caps for macros, such as "STANDARDSIZE".
• Where do braces go? Some people prefer ending the line with an open brace, then indenting the next line. Others like having the open/close braces on lines by themselves, indented with the rest. Still others like the latter, but without indenting them. Find one that everyone currently there can agree on, and enforce it, so that everyone can get used to seeing the braces one way, which improves debugging and code reviews, among other things, when you don't have to be getting used to ignoring a different brace style than what you are used to.
• How are variable names constructed? Some people have different prefixes/suffixes to signify things about the variables, such as the fact that they are global, or class members, and also what type of variable they are - ints, chars, pointers, etc.
  
  For example, at work, we use three-to-six letter prefixes to designate the type of the variable - intFiles is an int, chrpCurrent is a character pointer, etc.
• Indentation Standards? Some people don't believe this should be important, but it depends on how similar your development environments are. If you all use the same IDE, then this is unimportant. If, however, you develop on Unix/Linux with a wide range of editors (vim, emacs, kwrite, etc), then indentation needs to be standardized to have the display readable on each of these. Also, do you allow tabs or not?
• Comments? Yes, do use them. But, where are they required? The easiest place to require them is in the header for classes, for the public member functions. They should at least explain what the function does, what the arguments are that it takes, and what it returns. (I personally think that all functions, not just the public ones, need these. But perhaps that's just due to the fact that I can't interpret "int GetPtHitOn3dMseClk(int x, int y, int z)" very easily.)
• Spaces? Spaces need to be determined - as in, where are they absolutely required. At work, we use spaces, at a minimum, between math operators and after commas in a parameter list. Other places may also be useful.

I'm sure that there are other things to think about, which will be suggested, but these are places to start when considering a standard.

Linux

[sohp]

For the love of Dijkstra please don't use Hungarian style. There's a lovely common style in linux/Documentation/CodingStyle Which references (and bashes) the GNU Coding Standards. Either one of those could be a good starting point, once you resolve the fights you'll get into over style.

The proposed Boost C++ Coding Guidelines

[Rolf W. Rasmussen]

For C++, the best coding guidelines I've ever read is the proposed Boost C++ Coding Guidelines. (The link points to an old version in the boost CVS tree. To get an updated version you'd need to join the Boost Yahoo group and get it from the "Files" section of the group.

What I like about the guidelines is the well thought out rationales presented and its adherance to current C++ standards. After reading them, I wanted to follow the guidelines because I agreed with the rationale, rather than simply because the document said so.

Avoiding anal retentiveness...

[ChaoticCoyote]

Too many coding standards get into issues that are, quite frankly, ludicrous. If the programmers I hire can't handle slight differences in C++ brace placement, I need to find better programmers! Sheesh, I've never had problems following code because someone places the open bracket on the same line as the if, while I put mine on a subsequent line.

Having written for publication, I've had quite some experience with the anal retentive crowd. For example, I was excoriated for having an algorithm with 1-character variable names -- the code was, however, an implementation of a specific mathematical formula, and my code precisely matched variables in the original notation. To change the names to longer "descriptive" ones would have broken the continuity between definition (in a math text) and implementation (C++). The short names were actually more descriptive and accurate!

And then we have the "goto" wars -- I actually use a single goto in one of my books, bringing down the ire of mypoic ninnies (usually pre-degree college students) who only know that "gogot is bad" without a clue as to why they've been taught that. A rare, judicious goto can make code faster and more readable! But try telling that to fools who only parrot dogma... if a programmer can't understand the rare usefulness of a goto, they probably can't think far enough "outside the box" to be useful in the real world.

This isn't to say that I'm against coding standards -- I'm all in favor of them! But a coding standard should by flexible in nature and open-minded where practical; the goal is readable code and ease of typing. Programmers have habits, a rhythm when they type, and so long as their code follows broad guidelines of style. I'll take a dozen good comments and a solid design document over the placement of curly brackets any day!

Re:Avoiding anal retentiveness...

[sohp]

> If the programmers I hire can't handle slight differences in C++ brace placement, I need to find better programmers!

You've never actually written code as part of a large team using source control have you? Try figuring out the diffs between the code you have just modified and the code a fellow programmer just checked in after his favorite editor just automagically realigned all the braces! Few, if any, version control tools can automagically resolve that kind of conflict for you, so you have to do it yourself, or else pull the new version to a different location, re-re-align the braces, and do the diff then. Ugh. Pick a brace (and space/tab!) style, preferably one in common use and documented, and stick with it. It's not about the readability of one person's code, it's about the compatibility of changes across time and team members.

Re:Linux (what's wrong with Hungarian)

[sohp]

I'm pleased you asked.

• The naming hides the purpose of the variable under all the "warts".
• If a type changes, you're forced to rename your variables to reflect the new type.
• How do you pronounce it?
• Encourages sloppiness in variable naming: why spend time trying to find a meaningful name after you've written the type coding warts?
• If you don't know what your variable is for, knowing its type won't help you.
• prgrgpszDictionaryBase - a pointer to a two dimensional array of pointers to null-terminated strings
• 'nuff said

Re:For all the people that use VC++

[V. Mole]

No, please don't use Hungarian notation. In particular, please don't use Microsoft's bastardized version of Hungarian. Hungarian was invented for use with untyped and weakly typed languages (think assembler). See The Great Hungarian Prefix Swindle [www.keysound.org] for a well-though-out essay on the topic.

Well...

[ChaoticCoyote]

You've never actually written code as part of a large team using source control have you?

I dunno... 12 programmers at one shop, all using Source(un)Safe, working on a million-line e-banking app... seems like a "large team" to me.

I'm concerned with clarity of algorithm -- in other words, can I understand what the program is doing? That requires good comments, not curly-bracket placement.

You might have a point in regard to tabs/spaces, in that different people and systems have tabs set to different line positions. I've always specified hard spaces, so the code looks the same in everyone's editor and in print.

I'm not against programming standards -- I'm against getting into insane detail. I spend far more time trying to figure out someone's algorithm (or lack thereof!) than I do worrying about their brace style.

Re:For all the people that use VC++

[spongman]

I use hungarian exclusively and I find that it helps tremendously for both writing code and debugging. I learnt it on the job and while it was a little confusing at first it's pretty easy to get used to if you use it continuously. The main advantage, of course is that you instantly know the type of a variable without having to look for the definition. This is invaluable for pointer arithmetic and saves a great deal of time going through compiler warnings.

For example, the variable 'ppch' is a pointer to a pointer to a char (char **). 'p's and '*'s cancel each other so you know that the expression '(*ppch)' is a pointer to a char (char *) and '(**ppch)' is a char.

I also prefix member variables with 'm_' so there's never ambiguity between locals and members in member functions.

Usually the first thing I type is 'int main (int cArgs, char *rgszArgs [])'

Of course, it's not needed for strongly typed languages like C++/Java, but I still use it because it saves me time. I've heard some people complain that it adds too much time in typing - learn to type faster...

Re:Linux (what's wrong with Hungarian)

[spongman]

prgrgpszDictionaryBase - a pointer to a two dimensional array of pointers to null-terminated strings

Funny, when I read the 'prgrgpszDictionaryBase' part in my head i heard: 'a pointer to a two dimensional array of pointers to null-terminated strings'. Then I read your description and it seemed somehow redundant. I guess that's the point right there.

Re:For all the people that use VC++

[spongman]

Please excuse my ignorange, but I'm not sure what a QCanvasPixmapArray is. If it's an abstract datatype then I'd brobably use 'pqcpaExample, or if it's a (QCanvasPixmap *), then: 'rgqcpExample'. Generally such tricks don't cause any ambiguity especially given the context of the function or class that contains the code. I find that once you introduce such a mnemonic it's easy to spot its use in related code.

Sometimes if an OS header defines a struct 'SOME_OS_DATA_STRUCT', then I'll write code like:

SOME_OS_DATA_STRUCT sods;
sods.foo = 3;
::UseSODS (&sods);

I know it's lazy, and if I need more than one sods then I'll give them meaningful names like 'sodsThis' and 'sodsThat', but for a one-off it's not really necessary.

Mostly I do stuff like:

int cThings = CountThings ();
for (int iThing = 0; iThing < cThings; ++iThing)
{
CThing *pThing = rgThings [iThing];

I use STL alot too so I use alot of 'mapThings' and 'iterThing' and with ATL's CComPtr I use 'spThing' for smart-pointer. I don't adhere to the strict Simonyi notation - just enough to get by.

It helps me a great deal. Some people turn their noses up at it - I did too at first - but I recon it's worth a try.