Development:Code style - Revision history

Temporalbeing at 14:12, 4 June 2021

2021-06-04T14:12:02Z

Temporalbeing at 14:10, 4 June 2021

2021-06-04T14:10:17Z

Nikai: markup, sp

2010-06-25T06:32:19Z

markup, sp

safemode: /* Writing Pretty Code */

2008-02-20T17:48:37Z

‎Writing Pretty Code

safemode at 17:43, 20 February 2008

2008-02-20T17:43:02Z

New page

== 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.

@@ Line 51: / Line 51: @@
 '''Structural'''
-* Always include braces to denote blocks in C/C++
+* 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.
 ----
 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.

@@ Line 49: / Line 49: @@
 * 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.

@@ Line 1: / Line 1: @@
 == 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 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.
+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 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 lk code style].    Wrapping your code to 80 lines is optional, use what makes the code clear to read.
+Second, the linux kernel code guidelines are a good place to start.  [http://www.linuxjournal.com/article/5780 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.
+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.
@@ Line 13: / Line 13: @@
 * 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.
+* 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.
@@ Line 32: / Line 32: @@
 * 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)
+* 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.   Dont make it another Unit
+* IMPORTANT!!   Make sure your class is a represents a single object/thing.   Don't make it another Unit
 '''Functions'''
@@ Line 45: / Line 45: @@
 * 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.
+* 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.