C4Script Style Guidelines: Difference between revisions

Sven2 (talk | contribs)
Newton (talk | contribs)
m ->javadoc
Line 1: Line 1:
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:
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. Objects that have a public interface should be documented in a Javadoc-like syntax. Please adhere to this example if you edit or add new scripts.


=== Example ===
=== Example ===


  /*--
  /**
  ''Object title''
  ''Object title''
  Author: ''Author(s)''
  ''Description, including implementation details that might be interesting for other scripters''
   
   
  ''Description, including implementation details that might be interesting for other scripters''
  @author ''Author(s)''
  --*/
  */
   
   
   local some_variable;
   local some_variable;
   
   
  // ''Explanation of what the function does''
  /** ''Explanation of what the function does''
  public func DoSomething()
@param foo ''What the parameter foo is''
@return ''What comes out of this function''
*/
  public func DoSomething(int foo)
  {
  {
var foo = 1;
  // ''implementation commentars''
  // ''implementation commentars''
  if (foo == DIR_Left)
  if (foo == DIR_Left)
Line 43: Line 45:
* use spaces between operators like +, -, *, /, &&, || etc.
* use spaces between operators like +, -, *, /, &&, || etc.


Comments:
Comments and Documentation:
* especially for library objects or objects with an interface used by other objects, write an introductory comment including title, author(s) and a description
* 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 understand what you've done
* please comment your script where it is necessary for other scripters to understand what you've done
* Please use Javadoc-like syntax when documenting your code so that a reference can be automatically created from it later


Naming prefixes for IDs:
Naming prefixes for IDs:

Revision as of 23:17, 21 August 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. Objects that have a public interface should be documented in a Javadoc-like syntax. Please adhere to this example if you edit or add new scripts.

Example

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

	@author Author(s)
*/

 local some_variable;

/** Explanation of what the function does
	@param foo What the parameter foo is
	@return What comes out of this function
*/
public func DoSomething(int foo)
{
	// implementation commentars
	if (foo == DIR_Left)
	{
		some_variable++;
		CreateObject(:Goal_Melee);
	}

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

	return foo;
}

In words

Naming conventions:

  • generally, use meaningful identifiers which are self explanatory: e.g. weapon_strength rather than iStr
  • don't use hungarian notation, preferably use lowercase_separated_by_underscores
  • 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
  • {...} braces are not required for single line statements but can be added if it improves readability
  • use spaces between operators like +, -, *, /, &&, || etc.

Comments and Documentation:

  • 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 understand what you've done
  • Please use Javadoc-like syntax when documenting your code so that a reference can be automatically created from it later

Naming prefixes for IDs:

  • for libraries, icons and GUI elements: Library_*, Icon_*, GUI_*
  • for goals, rules and environment objects: Goal_*, Rule_*, Environment_*
  • for spells: Magic_
  • objects which are exclusively used by their parent objects should prefix their parent object name. e.g. ParkourCheckpoint for a checkpoint of the parkour goal

Misc:

  • For C4Script veterans: You don't need to write #strict 2 at the start of each script. All scripts are considered to be in strict 2 style
  • If you need multiple statements in a block, use one (if (...) { foo(); bar(); })! Avoid constructs like if (...) foo() && bar(); or if (...) Or(foo(), bar());