Development Team/Coding Standards - Revision history

Admin at 22:37, 11 September 2011

2011-09-11T22:37:27Z

Admin: /* Single Line */

2011-07-28T19:04:25Z

Single Line

← Older revision		Revision as of 19:04, 28 July 2011
Line 28:		Line 28:

	Single line comments should also be in the C style, for example:		Single line comments should also be in the C style, for example:
-	<~~source lang="~~c~~" line start=1~~ >	+	<c>
-	/*< This is a one-line comment. - SecretAgent /</~~source~~>	+	/*< This is a one-line comment. - SecretAgent /</c>

	Please avoid using C++-style single line comments (e.g. <code>// Something here</code>).		Please avoid using C++-style single line comments (e.g. <code>// Something here</code>).

Admin at 19:03, 28 July 2011

2011-07-28T19:03:26Z

← Older revision		Revision as of 19:03, 28 July 2011
Line 1:		Line 1:
	{{Header\|1 = <h2>'''[[Development Team\|DareNET Development Wiki]]''' - Coding Standards</h2>}}		{{Header\|1 = <h2>'''[[Development Team\|DareNET Development Wiki]]''' - Coding Standards</h2>}}
-	The following is a guide to explain the programming style used for ircd-darenet and services-darenet, and to advise future developers, creators or patches, or other maintainers in regards to desirable programming practices. Since these programs are based on the works of others (outside of the DareNET development team), it's reasonable to assume not all code will follow them. This, of course, will be rectified with time.	+	The following is a guide to explain the programming style used for ircd-darenet and services-darenet, and to advise future developers, creators of patches, or other maintainers in regards to desirable programming practices. Since these programs are based on the works of others (outside of the DareNET development team), it's reasonable to assume not all code will follow them. This, of course, will be rectified with time.

	== Comments ==		== Comments ==

Admin: /* Pointers */

2009-12-20T13:55:20Z

Pointers

← Older revision		Revision as of 13:55, 20 December 2009
Line 146:		Line 146:
	}</c>		}</c>

-	The above example informs the compiler that the function does not alter the contents (pointer to constant structure) of the external structure, and does not need to keep re-reading the contents each time they are accessed. It also ~~ensure~~ that the compiler will trap any accidental attempts by your code to write to the read-only structure.	+	The above example informs the compiler that the function does not alter the contents (pointer to constant structure) of the external structure, and does not need to keep re-reading the contents each time they are accessed. It also ensures that the compiler will trap any accidental attempts by your code to write to the read-only structure.

	=== Use of char pointers ===		=== Use of char pointers ===

Admin: /* Use of char pointers */

2009-12-20T13:54:15Z

Use of char pointers

← Older revision		Revision as of 13:54, 20 December 2009
Line 135:		Line 135:
	Struct names should be in camel case with a leading capital letter, for example, "MyBagOfBones". Variable names can be either in camel case with a leading capital letter or alternatively all lower case, so long as the same naming convention is adhered to throughout. Constants and enum values should always be completely in CAPITALS and underscores may be used.		Struct names should be in camel case with a leading capital letter, for example, "MyBagOfBones". Variable names can be either in camel case with a leading capital letter or alternatively all lower case, so long as the same naming convention is adhered to throughout. Constants and enum values should always be completely in CAPITALS and underscores may be used.

-	== ~~Use of char pointers~~ ==	+	== Pointers ==
	----		----
		+	Whenever possible, pass structures by reference (i.e., pass a pointer to the structure); otherwise, the whole thing will be copied onto the stack and passed, which can slow things down a bit. Functions receiving pointers to structures as arguments should declare them as pointer to <code>const</code> if the function is not going to alter the contents of the structure.
		+
		+	For example:
		+	<c>
		+	void print_data(const struct *data_pointer)
		+	{
		+	...printf contents of structure...
		+	}</c>
		+
		+	The above example informs the compiler that the function does not alter the contents (pointer to constant structure) of the external structure, and does not need to keep re-reading the contents each time they are accessed. It also ensure that the compiler will trap any accidental attempts by your code to write to the read-only structure.
		+
		+	=== Use of char pointers ===
		+
	Whenever you use char pointers (char, char*) try to use const equivalents. This is much safer and avoids ugly and dangerous casts.		Whenever you use char pointers (char, char*) try to use const equivalents. This is much safer and avoids ugly and dangerous casts.

Admin: /* Functions */

2009-12-20T13:43:20Z

Functions

← Older revision		Revision as of 13:43, 20 December 2009
Line 158:		Line 158:

	However, we do realize that it is sometimes hard to break things down. Since functions don't nest, variables have to be communicated through function arguments or global variables. Don't create huge interfaces to enable a decomposition that is just not meant to be.		However, we do realize that it is sometimes hard to break things down. Since functions don't nest, variables have to be communicated through function arguments or global variables. Don't create huge interfaces to enable a decomposition that is just not meant to be.
		+
		+	== Using switch() ==
		+	----
		+	For large decisions involving if...else...else..., it may be faster to use a switch.
		+
		+	For example:
		+	<c>
		+	if( val == 1)
		+	dostuff1();
		+	else if (val == 2)
		+	dostuff2();
		+	else if (val == 3)
		+	dostuff3();</c>
		+
		+	could be done as:
		+	<c>
		+	switch( val )
		+	{
		+	case 1: dostuff1(); break;
		+
		+	case 2: dostuff2(); break;
		+
		+	case 3: dostuff3(); break;
		+	}</c>
		+
		+	With if() statements, if the last case is required, all the previous ones will be tested first. The switch() statement allows us to cut out this extra work. If you must use a big if...else statement, test the most likely cases first.

	== Linefeeds ==		== Linefeeds ==

Admin: /* Use of char pointers */

2009-12-20T13:31:45Z

Use of char pointers

← Older revision		Revision as of 13:31, 20 December 2009
Line 138:		Line 138:
	----		----
	Whenever you use char pointers (char, char*) try to use const equivalents. This is much safer and avoids ugly and dangerous casts.		Whenever you use char pointers (char, char*) try to use const equivalents. This is much safer and avoids ugly and dangerous casts.
		+
		+	== Integers ==
		+	----
		+	Use unsigned ints instead of ints if you know the value will never be negative. Some processors can handle unsigned integer arithmetic considerably faster than signed. This is also good practice, and helps make for self-documenting code.

	== Macros ==		== Macros ==

Admin: /* Macros */

2009-12-20T13:27:40Z

Macros

← Older revision		Revision as of 13:27, 20 December 2009
Line 141:		Line 141:
	== Macros ==		== Macros ==
	----		----
-	Avoid them, if possible~~. We prefer that (inline) functions be used instead, as they provide better type checking and generally make code easier to read and debug~~.	+	Avoid them, if possible.

-	However, macros are fine for small, simple, often-repeated, run-to-completion code segments. For example, ff there is a small external function being called thousands of times in a tight loop, replacing it with a macro to perform the same job will remove the overhead of all those function calls. That said, they shouldn't be longer than six or so lines and they should never contain a return statement, or otherwise directly affect control flow of the calling function.	+	We prefer that (inline) functions be used instead, as they provide better type checking and generally make code easier to read and debug.
		+
		+	However, macros are fine for small, simple, often-repeated, run-to-completion code segments. For example, if there is a small external function being called thousands of times in a tight loop, replacing it with a macro to perform the same job will remove the overhead of all those function calls. That said, they shouldn't be longer than six or so lines and they should never contain a return statement, or otherwise directly affect control flow of the calling function.

	Also, remember that the text of a macro argument is "pasted in"; therefore, you should surround its arguments in parentheses to ensure they're evaluated before the rest of the macro body. This should also be done for the body itself to prevent the surrounding context from affecting the macro body.		Also, remember that the text of a macro argument is "pasted in"; therefore, you should surround its arguments in parentheses to ensure they're evaluated before the rest of the macro body. This should also be done for the body itself to prevent the surrounding context from affecting the macro body.

Admin: /* Macros */

2009-12-20T13:26:39Z

Macros

← Older revision		Revision as of 13:26, 20 December 2009
Line 141:		Line 141:
	== Macros ==		== Macros ==
	----		----
-	Avoid them, if possible. We prefer that (inline) functions be used instead, as they provide better type checking~~. And,~~ generally make code easier to read and debug.	+	Avoid them, if possible. We prefer that (inline) functions be used instead, as they provide better type checking and generally make code easier to read and debug.

	However, macros are fine for small, simple, often-repeated, run-to-completion code segments. For example, ff there is a small external function being called thousands of times in a tight loop, replacing it with a macro to perform the same job will remove the overhead of all those function calls. That said, they shouldn't be longer than six or so lines and they should never contain a return statement, or otherwise directly affect control flow of the calling function.		However, macros are fine for small, simple, often-repeated, run-to-completion code segments. For example, ff there is a small external function being called thousands of times in a tight loop, replacing it with a macro to perform the same job will remove the overhead of all those function calls. That said, they shouldn't be longer than six or so lines and they should never contain a return statement, or otherwise directly affect control flow of the calling function.

Admin: /* Macros */

2009-12-20T13:26:17Z

Macros

← Older revision		Revision as of 13:26, 20 December 2009
Line 141:		Line 141:
	== Macros ==		== Macros ==
	----		----
-	Avoid them, if possible. We prefer that (inline) functions be used instead, as they provide better type checking.	+	Avoid them, if possible. We prefer that (inline) functions be used instead, as they provide better type checking. And, generally make code easier to read and debug.

	However, macros are fine for small, simple, often-repeated, run-to-completion code segments. For example, ff there is a small external function being called thousands of times in a tight loop, replacing it with a macro to perform the same job will remove the overhead of all those function calls. That said, they shouldn't be longer than six or so lines and they should never contain a return statement, or otherwise directly affect control flow of the calling function.		However, macros are fine for small, simple, often-repeated, run-to-completion code segments. For example, ff there is a small external function being called thousands of times in a tight loop, replacing it with a macro to perform the same job will remove the overhead of all those function calls. That said, they shouldn't be longer than six or so lines and they should never contain a return statement, or otherwise directly affect control flow of the calling function.