C4Script Style Guidelines

Revision as of 19:25, 4 February 2017 by Maikel (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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
  • for variables don't use hungarian notation, preferably use lowercase_separated_by_underscores
  • for functions use CamelCase()
  • for static constants use PREFIX_Identifier
  • Prepend new style effects with Fx like FxNewStyleEffect

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.
  • keywords (if, while, for, etc.) are followed by a space.
  • function names are not followed by space, commas are

Access specifiers for object methods

Non-global methods that are part of a public interface and intended to be called from other objects or scripts, should be prefixed with the public keyword. As a part of the public interface of an object public methods should be documented with comments accordingly. Non-interface methods should be prefixed with the private keyword. Do not leave out the access specifier. The keyword protected is deprecated.

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
    C4Script
    1. #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());