C4Script Style Guidelines: Difference between revisions

Revision as of 17:36, 28 February 2010

Since many people are involved in the project, it is necessary to define some styling guidelines so that other developers can read your code more easily. Please adhere to this example if you edit or add new scripts:

Example

/*--
	Object title
	Author: Author(s)

	Description, including implementation details that might be interesting for other scripters
--*/

 local some_variable;

// Explanation of what the function does
public func DoSomething()
{
	var foo = 1;
	// implementation commentars
	if (foo == DIR_Left)
	{
		some_variable++;
		CreateObject(:Goal_Melee);
	}

	if (foo && some_variable)
		foo = foo + 1;

	return foo;
}

In words

Naming conventions:

use lowercase_separated_by_underscores for variables, not hungarian notation
use CamelCase() for functions
use PREFIX_Identifier for static constants

Indents, braces and spaces:

indent code with one tab
use the braces on own lines on the same indent level as the control structure / function declaration
use one space after a control structure
{...} braces are not required for single line statements but can be added if it improves readability
use spaces between operators like +, -, *, /, &&, || etc.

Comments:

especially for library objects or objects with an interface used by other objects, write an introductory comment including title, author(s) and a description
please comment your script where it is necessary for other scripters to better understand what you've done

Naming prefixes for IDs:

for libraries and GUI elements: Library_*, GUI_*
for goals, rules and environment objects: Goal_*, Rule_*, Environment_*
for spells: Magic_
prefixes for scenario-local objects and addon-packs

@@ Line 1: / Line 1: @@
-== Scripting policy ==
+Since many people are involved in the project, it is necessary to define some styling guidelines so that other developers can read your code more easily. Please adhere to this example if you edit or add new scripts:
-Style guideline for coding C4Script in OpenClonk.
+=== Example ===
-The development is based on exchange of scripts. Therefore it is necessary to define some styling rules, so that other developers can read your code more easily.
-=== Indentation ===
+ /*--
+ 	''Object title''
-Indent your code with tabs (ASCII 9). Use space (ASCII 32) for all other formatting.
+ 	Author: ''Author(s)''
-  public func foo()
+ 	''Description, including implementation details that might be interesting for other scripters''
+ --*/
+  local some_variable;
+ // ''Explanation of what the function does''
+  public func DoSomething()
   {
-  	bar();
+  	var foo = 1;
-  	if (1)
+ 	// ''implementation commentars''
+  	if (foo == DIR_Left)
   	{
-  		bar2();
+  		some_variable++;
+ 		CreateObject(:Goal_Melee);
   	}
- }
-=== Braces ===
-According to the [http://forum.openclonk.org/topic_show.pl?tid=208 poll] in the forum:
-Braces are on their own line, on the same level of indentation as the structure they belong to. You may add braces around single statements in if statements if the first block or an else block has them.
- if (bar)
- {
- 	foo();
- }
- else
- {
- 	foo2();
- }
-=== Spaces ===
-Keywords followed by a space: <tt>if, while, for</tt>
-Commas are followed by a space, function names not. <tt>-></tt>, <tt>->~</tt>, <tt>++</tt> and <tt>--</tt> don't need spaces, other operators do. <tt>+</tt> and <tt>-</tt> don't need spaces either when used as algebraic signs, otherwise they do.
- var foo = 0;
- foo++;
- if (foo && bar)
- {
- 	foo = foo + 1;
- }
-=== Control Structures ===
-Control structures with a single statements are written without braces. You may add braces for readability. Don't use shortcut operators instead of if.
-Statements are written in a new line.
-=== Comments ===
-'''Please comment your script where it's necessary.'''
-You may format your comments as you wish:
- // single line comment
- // multiline
+ 	if (foo && some_variable)
- // comment
+ 		foo = foo + 1;
- /* multiline
+ 	return foo;
-    comment 2 */
+  }
- // Unnecessary comment:
- // Increase i by one
- i++;
- // Necessary comment:
- // This starts the whole effect, casts particles and stuff
- CreateObject(BAR1, 0,0, GetOwner())->foo();
-Especially for German scripters: '''comment in English please!'''
+=== In words ===
-== IDs ==
+Naming conventions:
+* use <code>lowercase_separated_by_underscores</code> for variables, not hungarian notation
+* use <code>CamelCase()</code> for functions
+* use <code>PREFIX_Identifier</code> for static constants
-The difference with CR is that OC allowes for IDs to have more than four characters. The main OC content will use the namespace Core_, so use this as prefix for all your objects which go into the main object pack for OC.
+Indents, braces and spaces:
+* indent code with one tab
+* use the braces on own lines on the same indent level as the control structure / function declaration
+* use one space after a control structure
+* <code>{...}</code> braces are not required for single line statements but can be added if it improves readability
+* use spaces between operators like +, -, *, /, &&, || etc.
-=== Objects.c4d/Libraries.c4d ===
+Comments:
+* especially for library objects or objects with an interface used by other objects, write an introductory comment including title, author(s) and a description
+* please comment your script where it is necessary for other scripters to better understand what you've done
-ID's can now have more than four characters, so in the future use: Core_Library_.
+Naming prefixes for IDs:
+* for libraries and GUI elements: <code>Library_*</code>, <code>GUI_*</code>
+* for goals, rules and environment objects: <code>Goal_*</code>, <code>Rule_*</code>, <code>Environment_*</code>
+* for spells: <code>Magic_</code>
+* prefixes for scenario-local objects and addon-packs