Development:Code style

Writing Pretty Code

First off, you can avoid a lot of formatting issues with your code if you run it through 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. 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, don't 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. Don't 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 arithmetic 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. Don't 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 initialization. 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.

Structural

• Always include braces to denote blocks in C/C++. Many bugs come about because the braces were skipped for an initially single line block, that was then added to.
• Be explicit, not implicit. Don't rely on assumptions that may unknowingly break because the assumption changed.

---

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.