Development:Code style

Writing Pretty Code

First off, you can avoid a lot of formatting issues with your code if you run it through http://invisible-island.net/bcpp/bcpp.html link bcpp]. This is a formatter that will give you something that fixes your brace placement and indentation (for the most part). Always proof read the output. Make sure preprocessor macros start at the beginning of the line.

Second, the linux kernel code guidelines are a good place to start. [ http://www.linuxjournal.com/article/5780 link lk code style]. Wrapping your code to 80 lines is optional, use what makes the code clear to read.

for both headers and cpp's, make sure you have an endline at the end of the file. Please, dont edit in notepad, it makes crappy dos endlines. Use wordpad or better if in windows land.

The following guidelines are in addition to the kernel code style guidelines.

Headers

• Headers really shouldn't contain any code unless it is inline.
• Headers should try and limit the amount of forward definitions used. It's usually a sign of api corruption to have a list of more than a couple forward declarations.
• Only include the headers you need for that specific header to compile. Dont include headers your cpp file needs but header doesn't.
• When using objects from a different namespace, never "using" that namespace in the header. reference such objects fully.
• Avoid the multiple uses of "private" and "public" keywords when declaring a large class.
• Fully document your headers, defining valid / invalid arguments
• make static variables part of the class that uses them whenever possible

Source (cpp files)

• Always include system headers before project headers.
• Never put header includes after a "using namespace" directive.
• Include only the headers you need.
• Try to only use "using namespace " to use a specific class when it makes sense.
• Comments should be in headers, but in pieces of complex code (algos and weird loops/constructs) comments are required. Do not comment functions, that should be done in headers, unless the function doesn't exist in the header.

Classes

• Make as much of the class as private as possible.
• Only structs should really allow direct access to elements in the class.
• Classes are default private, so it's ok to skip the private keyword when it comes first.
• Classes should be complete. equal operators must be defined. If it makes sense someone might do arithmatic with your class, those should be handled as well. (vectors, points, etc)
• Inherit only when absolutely necessary. Never do multiple inheritance.
• Use inline functions only for very small functions (in some cases, it's acceptable on high frequency code paths).
• Use const returns and functions whenever possible. This is important.
• Try to not allow direct pointer access to elements whenever possible.
• IMPORTANT!! Make sure your class is a represents a single object/thing. Dont make it another Unit

Functions

• We have an Error class. Use it.
• Always return errors when appropriate. Do not make it the responsibility of some caller to guess your error if your function can error in more than one way.
• Keep Functions as small as possible. Avoid multiple empty lines. Keep to the rule, one purpose per function.
• Reuse temp variables when possible.
• Always initialize variables if they can be used prior to initializiation. Do not rely on OS specific behavior.
• When dealing with conditionals, place exit conditionals first, then the most common case conditionals next.
• Be aware of the cost of your function in cpu time. Even if it's not in a fast-code path.

---

These are guidelines written by safemode. Feel free to annotate or alter them where needed. They are not yet set in stone as no official guideline has been ratified by project leaders.