Keep the coding standards short and sweet too, or people won't read it. A company I worked at had a coding standard that was around 30 pages long, and in addition to the standard "tabs should be exactly 4 spaces" junk, it was filled with bad advice and tips like "always use std::endl instead of '\n'". I imagine I was the only one who read it.

If you want to know more about code review, smartbear has a free book including studies, various methods, etc.: http://smartbear.com/codecollab-code-review-book.php

They're basically trying to sell their software; but, hey, it's a great read, and free!

@Martin: I definitely agree with you there! The standard should read in order of importance and anything after the first few pages should be treated as optional.

@Andrew: Thanks for that, I've ordered a copy of the book. I had been intending to read a bit about the subject, but I wanted to braindump beforehand. :)

I actually disagree with this big focus on a "coding standard" aka syntax bible. At first it sounds reasonable, it would "improve code readability" and so on... but in actual practice, one quickly realizes questions of code syntax in game development (and most coding, really) just aren't important at all. They're not a real source of errors and it's simply not worth it to spend time on syntax. So what if the AI guys prefix their floats with f and the physics guys don't.

When doing a code review, just focus on the actual high-level reasoning behind the code, make sure it's globally understandable and makes sense in the context of the project, look out for any risks to the rest of the codebase, and please, don't sweat the underscores.

I'm a fan of just the 'simple stuff' for coding standards. Standards like use mCamelCase for member variables, explicit imports vs .* imports, set tab width and use of strictly spaces are good to me. Standards that either take little effort or can be done automatically by an IDE are really nice to keep code clean. Anything that requires a devoted effort or cause convoluted coding situations are more trouble than they are worth.

For me standards aren't really about code formatting issues. I don't much care about underscores, prefixes for floats, or where people put their braces. For those kinds of things I would still say it's a good idea that everyone follow the same conventions, but I wouldn't get religious about it.

"look out for any risks to the rest of the codebase"

This is the most important thing, but I think it should include things like const-correctness, protecting member variables, and other best practices. I would imagine that to most coders it seems obvious to initialise all your members variables, but some coders might not want to for performance reasons. If it's in the standard then it shortcuts any arguments, and basically the standard takes the role of a moderator in the code review.

"If it's in the standard then it shortcuts any arguments, and basically the standard takes the role of a moderator in the code review."

I would argue that this is not a positive thing. You just gave an example where not initializing a variable would make sense, and you can probably think of many where it wouldn't. Having something like "Always initialize all variables." in a standard wouldn't really be a positive thing then, since as you see it, you just can't argue with the Standard. Even more dangerous is the place where you basically say that you don't care what's in the standard, just that it exists.

It's a way to abdicate in the face of actual problems, and is in no way a solution. If there are heated arguments about which way to code something, then that's a hint that it's not the kind of argument best solved by a far-reaching standard. Except in the case of syntax, where basically nobody should really care anyway.

I gave an example of where someone might argue that not initializing a variable would make sense. In practice though it is very rare to have a valid reason for not initializing a variable. There are exceptions to every rule, so there does needs to be some flexibility, but the 1% of exceptions shouldn't mean that we don't bother with a standard at all.

You should be able to argue against the standard, but you would have to have a good case for it.

"Even more dangerous is the place where you basically say that you don't care what's in the standard, just that it exists."

I was talking there about formatting/syntax issues, which I realise isn't clear. Any coder should be able to adapt their coding style to suit whatever conventions exist in the codebase he is working with. So in that sense it shouldn't matter what the formatting conventions are so much. As you said yourself "don't sweat the underscores". I think it is important though that everyone stick to same style when working in the same code base. It improves readability.When you can go anywhere in the code base and be assured that the conventions are the same then things just go that little more smoothly.

@Louis

Louis, i seriously doubt that you have any experience at all coding on the sizable project. The kind of project which required more than a couple of coders banging out code in the basement somewhere. The project which would take years to complete.

At first coding standard would seem like an un-required rubbish, but think about it carefully.

In you own words :

"So what if the AI guys prefix their floats with f and the physics guys don't."

This is exactly the point of having the coding standard in-place. What if your Physics guys choose to opt their own special coding practices while the rest of the team is on the difference standard and the guy left in the middle of project? Now, no one on the team know about that guy's standard practices and have to dig deep into his code to be able to fix bugs or write some more functionality using his code base. It would take ages to wrap your mind-set around this guy's standard and be able to pin-point the bug in the code or understand how to use his code base. The time would be better spend elsewhere.

Further more consider this example :
//Java is used for reading simplicity here

String aString = "text not yet encoded";
String bString = Encoder.encode(aString);

// some more lines of code ... and you suddenly see this

bString = aString;

Didn't you spotted the wrong? This code would get no complaint from the compiler since its technically correct (a string can be assigned onto another string). But if your code expect a string which has already been encoding and do Decoder.decode(bString) would get rubbish.

What if the standard said you need to add "_es" suffix for every encoded string the code would look like :

String aString = "text not yet encoded";
String aString_es = Encoder.encode(aString);

and when you see

aString_es = aString;

This would certainly raise a suspicious about the code. It help coders on a different team spotted the run-time bug quickly.

Cheers

@Jeff

A while ago the company i worked for opt apply for ISO 9001/2008 for software design / delivery. There will be a section in the standard process doc which called "tailoring process" which means the team can create the exception to the rules if it required.

The point here is to see what is the best way to tackle a project. If the project required not initialize variable in favor of speed, then by all mean do it, but it need to be done "as a team". The whole team need to understand what the rules are and what are the exceptions for particular project or no body will bother following the rule and wreck havoc.

I work on the DS, which is about as low-end as it gets, and we initialise all our variables and it doesn't come up in profiling. I guess it could become an issue in theory, but it is pretty rare. I did say though that the standard should have some flexibility. Blindly following any set of rules can lead you into trouble, but throwing out the standard because of a few rare exceptions will get you into far more. You should initialise every variable IMO and then only if it comes up in profiling think about not initialising it. It is the worst kind of premature optimisation if you do it without profiling first.

I agree that reviews should be relaxed. I completely disagree that they should be eliminated based on seniority. Noone should be arrogant enough to think that they never make mistakes and can never learn from others on their team. Code reviews also spread knowledge among the programming team. It might make sense to have a rule that says only a senior coder can review a junior coders work, but everyones work gets reviewed. I think to do otherwise undermines the whole process and would cause resentment.

If people see them as a gigantic pain then either the process needs streamlining or people don't understand the reasoning behind them.

@Sutthipong

"The whole team need to understand what the rules are and what are the exceptions for particular project or no body will bother following the rule and wreck havoc. "

You put it better than I possibly could, thanks!

Thanks that was an interesting read. Between what you wrote and the comments here it does highlight the difficulty of creating policy that is universally applicable. It seems to me like you spend a couple of years in university learning the rules of programming and then the rest of your career learning when they don't apply.

@Sutthipong I think naming is actually one of the places where it is very hard to give a meaningful and workable policy that helps. You gave an example relating to handling of encoded and unencoded strings and suggested """What if the standard said you need to add "_es" suffix for every encoded string the code would look like :

String aString = "text not yet encoded";
String aString_es = Encoder.encode(aString);"""

I suspect that if you are standardising naming at that level, your standard will likely be very large, very quick. In your example it is trivial to convert the class structure to a form where the compiler can check for the error so that it is impossible to mishandle encoded strings.

String s = "text not yet encoded";
EncodedString es = Encoder.encode(s);
s = es; // compile time error
es = s; // compile time error

@Chris "Throwing out the standard because of a few rare exceptions will get you into far more." A good standard would hopefully have very few exceptions. I think standardising at the right level is important. You are arguing in favour of initialising all variables. For my work I would potentially disagree with that one. A more general suggestion is that all objects should exist in a well defined state. An object may contain unitialized variables if it's state is still well defined. For example, std::vector in C++ references memory that is both initialized and unitialized and yet always has a well defined state. Religiously zeroing all variables/members impedes your ability use valgrind and similar debugging tools to detect variables that are used before they are assigned a meaningful value.

Thanks again for the interesting read.