Slashdot Mirror
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?"
The Sun link you gave is the standard for Java, as i'm sure you know. People will bitch and moan about being forced into one true brace style or not being able to use underscores in variable names, etc., but after a while, they'll get used to anything, and it really does help when all code is in the same format. Just make sure that your people obey the standards better than sun does (they break their own rules all over the place in the java tutorial and java src code).
Coding Conventions
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.
"Well, put a stake in my heart and drag me into sunlight."
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.
"I see. The fact that you...`can't explain'.. explains everything."
Mozilla's standards are great, if you want to use what little bit of C++ will work on every compiler on the planet.
This depends of course on the nature of your project, but I think it's fair to assume a non-decrepit compiler. If Visual C++ 1.5 breaks a certain feature, well, Visual C++ 6.0 has been out for over 2 years now.
There are a lot of really useful parts of C++ that are actually fairly well worked out on most modern compilers. For instance, templates are damn handy. There may be some differences between the level of support, but there is generally a very large subset of C++ templates that works on most modern compilers. And they let you do things that make all the rest of the programming safer and easier, like generic containers, like smart pointers.
Trees can't go dancing
So do them a big favor
Pretend dancing stinks!
This is a definite must read.
-------------------------------------------------
charlton heston is more of a man than yo
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:
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".
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.
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.
Face it, its one of the most used compilers in the world (if not THE most used compiler in the world). VC++ that is, and MS has their own style of notation, you've probably heard of it, called Hungarian notation.
t ion.htm
Very popular, a little hard to use, but will save you a ton of time.
Did a quick search on Google and got some really good results on how to use Hungarian notation:
http://www.umr.edu/~cpp/common/hungarian.html
http://csciwww.etsu.edu/bailes/1250/HungarianNota
Just to name a few. I use it in all of my major projects (see sig for shameless plug) and I hope that many other people will adopt it into their coding styles.
-Vic
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.
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.
- Rolf W.
Here's another Java style guide
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!
All about me
We've successfully used Rogue Wave's Elements of Java Style conventions on most of our projects. Of course, people will still disagree on curly braces, indentation, tabs vs. spaces, but on the whole if you have the style guide as a hardcopy book, it'll be a lot easier to settle disputes and point out the standard. And it saves a helluva lot of time for the poor sucker on the team who has to write the coding standards if he can concentrate on project-specific usage patterns and framework notes instead of detailing where curly braces go and how to write variable names.
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.
All about me
tr00l
I am not sure how similar C# is to Java
but following the Microsoft recommendations in the Framework SDK might be a good idea - they seem pretty well thought out.
In particular, check out the "Naming Guidelines" section,
though the entire set of design guidelines is also good reading.
For example, if you look at the Win32 API (sorry; that's what I'm most familiar with) you will find the following mechanisms used to return error status:
- BOOL - If FALSE, call GetLastError() to retrieve the Win32 status. Example: CreateProcess().
- HANDLE - If INVALID_HANDLE_VALUE, call GetLastError() to retrieve the Win32 status. Example: CreateFile().
- HANDLE - If NULL, call GetLastError() to retrieve the Win32 status. Example: CreateFileMapping().
- DWORD - If some distinguished value (0? -1?), call GetLastError() to retrieve the Win32 status. Example: TlsAlloc().
- DWORD - The Win32 status code. Example: RegQueryValueEx() - this API actually returns a LONG, not a DWORD, but you get the point.
- HRESULT - The COM status code. Example: GetSiteNameFromSid().
There are also NT kernel APIs that fail by raising exceptions. The caller must wrap the API in a try/except handler to catch the exception and retrieve the error code.It's not just the Win32 API that uses these mechanisms for returning status. I've seen app code that duplicates each of these. I've also seen coding errors caused by the programmer not checking for the correct condition. For example, if the app contained a function called OpenFileAndCreateMapping() that returned a HANDLE, how would you test the return value to determine if an error occurred? Test for NULL? INVALID_HANDLE_VALUE? Some other distinguished value?
The last coding style guide I created for a large project mandated that any function that can possibly fail must return a DWORD containing the Win32 status code. This made the code easier to write, review, and maintain.
KM
For C/C++, I use 'indent'. I don't do much Java but another poster here suggested the pretty-printer.
My opinion? See above.
I used to be the first one in line to help develop coding standards. Now, I can't imagine wasting my time with them. I attribute it to being young and not having enough experience -- thinking that I had seen everything worth seeing. I have now seen some of the most beautiful code written in a style that most people balk at. It expresses its beauty through its amazing ideas, exquisit symetry, and ingenious compactness. Looking at an entire interpreter written as a page of APL while actually writing in C.
I used to be a syntax bigot, but I have now seen the light (no, Perl is still ugly and unreadable with no redeaming quality, unlike the almost prefectly regular syntax and symantics of K). No coding standard can make good code, but good code could be prevented by coding standards.
Remember, only you can help prevent segmentation faults.
-j
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.
For example, if you want to associate some code with a Swing button click, you have to implement the interface "ActionListener" by writing a method called "actionPerformed." You are just going to confuse things if you try to enforce a different set of conventions for your own code, like "mActionPerformed" or "IActionListener".
In my own projects, I also insist that every class and method start with a javadoc comment containing at least one descriptive sentence, and it is not allowed to be a cut-and-paste comment from some other class or method.
A coding standard can pretty much make unreadable lame code into readable lame code.
The code is more maintainable, but slighty more time consuming to create.
A beautiful one liner is great, but if it takes someone else two minutes to figure out, that's a wasted two minutes, elegant or not.
My point was missed, I think. If you can express the code concisely -- I can view the entire algorithm in one page -- then it is easier to see the big picture while walking through the details. You do not need to keep scrolling around the source. It is possible to site back and just immerse yourself in it.
Oh. Cool. Yeah, sorry about that. I couldn't agree more.