Coding guidelines - Revision history

Timo 6: Update categories

2012-09-01T10:57:42Z

Update categories

Timo 6: Timo 6 moved page Coding Guidelines to Coding guidelines: Use lower case for consistency

2012-08-27T13:07:14Z

Timo 6 moved page Coding Guidelines to Coding guidelines: Use lower case for consistency

Timo 6: Update link

2012-08-27T13:06:21Z

Update link

Timo 6: 12 revisions: Import from old wiki (on 15 May 2012)

2012-08-26T17:19:03Z

12 revisions: Import from old wiki (on 15 May 2012)

New page

==File extensions==
Header files have .h extensions.
Source implementation files have .cpp extensions.

==Code==
VDrift code is formatted using all tabs and no spaces. The following example demonstrates VDrift's coding style.

class EXAMPLECLASS
{
private:
int data;

public:
EXAMPLECLASS();
~EXAMPLECLASS();

void MemberFunction();
};

// Add the sum of the number 1 - 10 to data.
void EXAMPLECLASS::MemberFunction()
{
// loop and add i to data <-- Useless comment, should be avoided.
for (int i = 1; i <= 10; i++)
{
data += i;
}
}

==Indentation and Naming==

Notice the use of ALL CAPS for class names. Function names should be presented in MixedCase?. Opening and closing curly brackets ({}) should be on their own line, and should not be indented. The enclosed statements however, should be indented.

Control statements should have one space between the statement and the left paren. There should be no padding inside of the parens unless it helps readability, use your judgement. Function calls should have no spaces between the function name and the left paren.

==Commenting==

Do not overuse comments. Only comment code which has side effects, is not clear at first glance, or includes complex operations. It is OK to comment a section of code with a description of what that section does.

It is a good idea to comment most non-trivial classes, methods, and instance variables. When commenting code, keep in mind that using [http://doxygen.org/ Doxygen] style comments will help to generate better documenation. See [[Source Code Documentation]] for more information.

==Inheritance==

Inheritance is generally discouraged ''except'' in simple cases where the base class is abstract and there is only one level of inheritance.

In general, excessive use of inheritance compromises code readability and could be easily fixed by using a member variable instead of inheritance. For example, instead of making CAR inherit from ENGINE, the CAR should contain an ENGINE member.

==Coupling/Dependency==

Coupling (or dependency) is the degree to which each program module relies on each one of the other modules. Coupling should be eliminated between unrelated modules. De-coupling modules leads to greater code cohesion, and high cohesion is associated with several desirable traits of software including robustness, reliability, reusability, and understandability whereas low cohesion is associated with undesirable traits such as being difficult to maintain, difficult to test, difficult to reuse, and even difficult to understand.

Program module (class) dependencies should be structured in a tree form, where higher level modules know about lower level modules, but lower level modules don't know about each other. For example, if there is a GAME module that contains a RENDERER module and a SETTINGS module, the code inside the GAME module should query the SETTINGS module and then initialize the RENDERER appropriately. That is, the GAME module would tell the SETTINGS module to go read the configuration file, ask the SETTINGS class "what's the display resolution supposed to be? how many bits per pixel? etc", and then make its calls to the RENDERER saying "okay, set up a display with this resolution, this many bits per pixel, etc". The RENDERER should ''not'' know anything about the SETTINGS module and should not access it. The advantage is that now the RENDERER doesn't need to know anything about a SETTINGS subsystem (and vice versa). If the SETTINGS subsystem is later rewritten, it doesn't (and shouldn't ever) cause any changes to code in the RENDERER. The RENDERER is now decoupled from the SETTINGS subsystem, and can now be re-used in a different project with a completely different SETTINGS subsystem. Decoupling also makes thread-safe coding easy.

Globals and singletons cause excessive coupling due to their global-access properties and should be completely avoided.

==Namespaces==

Classes are declared in the global namespace, but can also be put in custom namespaces if appropriate.

No include file should pollute the global namespace with a "using" directive. That is, lines such as "using namespace std" should not occur in any header (.h) file. All "using" directives should be put into the implementation source files (.cpp). This is because any source file that includes a header with a using directive will have its global namespace unexpectedly polluted in whatever way the header file specifies.

For "using" directives in .cpp files, specific "using" declarations are preferred to "using namespace" declarations. That is, prefer "using std::string", "using std::endl", etc to "using namespace std". This is for readability.

==Testing==

Unit testing is encouraged. VDrift comes with the [http://quicktest.sourceforge.net QuickTest] unit testing framework. To use, simply #include "unittest.h" in your source code implementation files.

{{note|Currently, not all of VDrift's code follows these guidelines, do not waste time cleaning up the code, unless you are re-writing that particular piece of it. There will be a time when the code will be cleaned up. Also code from the Vamos project, does not follow these guidelines either. Make sure all new code written for VDrift follows these guidelines.}}

[[Category:Development]]
[[Category:Documenting]]
[[Category:Expand]]

Venzon at 23:42, 15 May 2008

2008-05-15T23:42:52Z

Venzon at 19:09, 15 May 2008

2008-05-15T19:09:46Z

Venzon at 19:09, 15 May 2008

2008-05-15T19:09:16Z

Venzon at 19:05, 15 May 2008

2008-05-15T19:05:03Z

Venzon at 19:04, 15 May 2008

2008-05-15T19:04:29Z

Venzon at 19:02, 15 May 2008

2008-05-15T19:02:43Z

← Older revision		Revision as of 10:57, 1 September 2012
Line 63:		Line 63:

	[[Category:Development]]		[[Category:Development]]
−	~~[[Category:Documenting]]~~
−	~~[[Category:Expand]]~~

@@ Line 40: / Line 40: @@
 ==Inheritance==
-Inheritance is generally discouraged [[except]] in simple cases where the base class is abstract and there is only one level of inheritance.
+Inheritance is generally discouraged ''except'' in simple cases where the base class is abstract and there is only one level of inheritance.
 In general, excessive use of inheritance compromises code readability and could be easily fixed by using a member variable instead of inheritance.  For example, instead of making CAR inherit from ENGINE, you should have CAR contain an ENGINE member.

@@ Line 40: / Line 40: @@
 ==Inheritance==
-Inheritance is generally discouraged EXCEPT in simple cases where the base class is abstract and there is only one level of inheritance.  In general, excessive use of inheritance compromises code readability and could be easily fixed by using a member variable instead of inheritance.  For example, instead of making CAR inherit from ENGINE, you should have CAR contain an ENGINE member.
+Inheritance is generally discouraged [[except]] in simple cases where the base class is abstract and there is only one level of inheritance.
 ==Coupling/Dependency==

← Older revision	Revision as of 13:07, 27 August 2012
(No difference)

@@ Line 29: / Line 29: @@
 ==Indentation and Naming==
 Notice the use of ALL CAPS for class names. Function names should be presented in MixedCase?. Opening and closing curly brackets ({}) should be on their own line, and should not be indented. The enclosed statements however, should be indented.
@@ Line 35: / Line 34: @@
 ==Commenting==
 Do not overuse comments. Only comment code which has side effects, is not clear at first glance, or includes complex operations. It is OK to comment a section of code with a description of what that section does.
-It is a good idea to comment most non-trivial classes, methods, and instance variables. When commenting code, keep in mind that using [http://doxygen.org/ Doxygen] style comments will help to generate better documenation. See [[Source Code Documentation]] for more information.
+It is a good idea to comment most non-trivial classes, methods, and instance variables. When commenting code, keep in mind that using [http://doxygen.org/ Doxygen] style comments will help to generate better documenation. See [[Source code documentation]] for more information.
 ==Inheritance==
 Inheritance is generally discouraged ''except'' in simple cases where the base class is abstract and there is only one level of inheritance.
@@ Line 47: / Line 44: @@
 ==Coupling/Dependency==
 Coupling (or dependency) is the degree to which each program module relies on each one of the other modules.  Coupling should be eliminated between unrelated modules.  De-coupling modules leads to greater code cohesion, and high cohesion is associated with several desirable traits of software including robustness, reliability, reusability, and understandability whereas low cohesion is associated with undesirable traits such as being difficult to maintain, difficult to test, difficult to reuse, and even difficult to understand.
@@ Line 55: / Line 51: @@
 ==Namespaces==
 Classes are declared in the global namespace, but can also be put in custom namespaces if appropriate.
@@ Line 63: / Line 58: @@
 ==Testing==
 Unit testing is encouraged.  VDrift comes with the [http://quicktest.sourceforge.net QuickTest] unit testing framework.  To use, simply #include "unittest.h" in your source code implementation files.

@@ Line 42: / Line 42: @@
 Inheritance is generally discouraged ''except'' in simple cases where the base class is abstract and there is only one level of inheritance.
-In general, excessive use of inheritance compromises code readability and could be easily fixed by using a member variable instead of inheritance.  For example, instead of making CAR inherit from ENGINE, you should have CAR contain an ENGINE member.
+In general, excessive use of inheritance compromises code readability and could be easily fixed by using a member variable instead of inheritance.  For example, instead of making CAR inherit from ENGINE, the CAR should contain an ENGINE member.
 ==Coupling/Dependency==
@@ Line 48: / Line 48: @@
 Coupling (or dependency) is the degree to which each program module relies on each one of the other modules.  Coupling should be eliminated between unrelated modules.  De-coupling modules leads to greater code cohesion, and high cohesion is associated with several desirable traits of software including robustness, reliability, reusability, and understandability whereas low cohesion is associated with undesirable traits such as being difficult to maintain, difficult to test, difficult to reuse, and even difficult to understand.
-Program module (class) dependencies should be structured in a tree form, where higher level modules know about lower level modules, but lower level modules don't know about each other.  For example, if I have a GAME module that contains a RENDERER module and a SETTINGS module, the code inside the GAME module should query the SETTINGS module and then initialize the RENDERER appropriately.  That is, the GAME module would tell the SETTINGS module to go read the configuration file, ask the SETTINGS class "what's the display resolution supposed to be? how many bits per pixel? etc", and then make its calls to the RENDERER saying "okay, set up a display with this resolution, this many bits per pixel, etc".  The RENDERER should NOT know anything about the SETTINGS module and should not access it.  The advantage is that now your RENDERER doesn't need to know anything about a SETTINGS subsystem (and vice versa). If you later completely rewrite your SETTINGS subsystem, it doesn't (and shouldn't ever) cause you to touch any code in your RENDERER. Your RENDERER is now decoupled from your SETTINGS subsystem, and can now be re-used in a different project with a completely different SETTINGS subsystem.  Decoupling also makes thread-safe coding easy.
+Program module (class) dependencies should be structured in a tree form, where higher level modules know about lower level modules, but lower level modules don't know about each other.  For example, if there is a GAME module that contains a RENDERER module and a SETTINGS module, the code inside the GAME module should query the SETTINGS module and then initialize the RENDERER appropriately.  That is, the GAME module would tell the SETTINGS module to go read the configuration file, ask the SETTINGS class "what's the display resolution supposed to be? how many bits per pixel? etc", and then make its calls to the RENDERER saying "okay, set up a display with this resolution, this many bits per pixel, etc".  The RENDERER should ''not'' know anything about the SETTINGS module and should not access it.  The advantage is that now the RENDERER doesn't need to know anything about a SETTINGS subsystem (and vice versa). If the SETTINGS subsystem is later rewritten, it doesn't (and shouldn't ever) cause any changes to code in the RENDERER. The RENDERER is now decoupled from the SETTINGS subsystem, and can now be re-used in a different project with a completely different SETTINGS subsystem.  Decoupling also makes thread-safe coding easy.
 Globals and singletons cause excessive coupling due to their global-access properties and should be completely avoided.

@@ Line 62: / Line 62: @@
 ==Testing==
-Unit testing is encouraged.  VDrift comes with the [quicktest.sourceforge.net QuickTest] unit testing framework.  To use, simply #include "unittest.h" in your source code implementation files.
+Unit testing is encouraged.  VDrift comes with the [http://quicktest.sourceforge.net QuickTest] unit testing framework.  To use, simply #include "unittest.h" in your source code implementation files.
 {{note|Currently, not all of VDrift's code follows these guidelines, do not waste time cleaning up the code, unless you are re-writing that particular piece of it. There will be a time when the code will be cleaned up. Also code from the Vamos project, does not follow these guidelines either. Make sure all new code written for VDrift follows these guidelines.}}

← Older revision		Revision as of 19:09, 15 May 2008
Line 59:		Line 59:

	For "using" directives in .cpp files, specific "using" declarations are preferred to "using namespace" declarations. That is, prefer "using std::string", "using std::endl", etc to "using namespace std". This is for readability.		For "using" directives in .cpp files, specific "using" declarations are preferred to "using namespace" declarations. That is, prefer "using std::string", "using std::endl", etc to "using namespace std". This is for readability.
		+
		+	==Testing==
		+
		+	Unit testing is encouraged. VDrift comes with the [quicktest.sourceforge.net QuickTest] unit testing framework. To use, simply #include "unittest.h" in your source code implementation files.

	{{note\|Currently, not all of VDrift's code follows these guidelines, do not waste time cleaning up the code, unless you are re-writing that particular piece of it. There will be a time when the code will be cleaned up. Also code from the Vamos project, does not follow these guidelines either. Make sure all new code written for VDrift follows these guidelines.}}		{{note\|Currently, not all of VDrift's code follows these guidelines, do not waste time cleaning up the code, unless you are re-writing that particular piece of it. There will be a time when the code will be cleaned up. Also code from the Vamos project, does not follow these guidelines either. Make sure all new code written for VDrift follows these guidelines.}}

@@ Line 1: / Line 1: @@
 ==Code==
 VDrift code is formatted using all tabs and no spaces. The following example demonstrates VDrift's coding style.
@@ Line 32: / Line 36: @@
 ==Commenting==
 Do not over use comments. Only comment code that has side effects, is not clear at first glance, or that does complex operations. It is ok to comment a section of code with a comment describing what that section does.
 {{note|Currently, not all of VDrift's code follows these guidelines, do not waste time cleaning up the code, unless you are re-writing that particular piece of it. There will be a time when the code will be cleaned up. Also code from the Vamos project, does not follow these guidelines either. Make sure all new code written for VDrift follows these guidelines.}}