Much of this was extracted from Taligent's Guide to Designing Programs[[2]].
We probably need one if we want to have the right to use the code after we leave, but we won't know what it is for a while.
There are three different places for comments, within the class/function, before the class/function and at the top of a file. The top of the file should contain a description of what is in the file and what it was meant to be used for.
Comments before class or function declarations give detailed information on how the function is to be used, and important pre or post conditions (such as who is responsible for deleting memory), and anything else a user needs to be able to use the function or class without looking at the implementation. The syntax for comments is described more fully in the Documentation section.
With a function or class body keep the comments short and concise. Echo the code as little as possible, but if the code isn't completely obvious include a comment. There is a rule of programming that states ``If the code and the comments disagree, chances are they are both wrong''. If you come across places where the comments are wrong, treat it like a bug and fix it.
Use dummy parameters for function declarations. This make the code much more readable. For example is SetCameraPosition(const RiVector &, const RiVector &) meant to be SetCameraPosition(const RiVector &eyePoint, const RiVector &viewDirection) or SetCameraPosition(const RiVector &eyePoint, const RiVector &lookAtPoint)? If you are getting compiler warnings about unused variables, take the parameter out of the function definition, not the declaration. Parameters in the declaration don't give warnings.
Almost all macros and #defines can be replaced by inlined functions and const variable. Use these whenever possible as they are typesafe and many problems will be more easily caught at compile time.
Don't include more include files then are necessary. Extra includes slow down compiles. They also make understanding the dependenies between files difficult, which can make changing the software more difficult.
On the other hand, include all files that are needed. Don't rely on other include files to include the ones you use. Removing dependencies from those might break yours.
There is little more frustrating than searching through too many include files for the problem you are looking for, having to do a manual recursive search, or adding #include's to a lot of other people's files once you simplify something you are working on.