This document is a short guide on the generally accepted naming conventions and other aspects of Pawn source code to aid easier communication of intent and streamline debugging and sharing of code.
A statement is a piece of code that imperatively tells the host program to do something. A statement is a valid piece of code that yields some result.
This is a statement composed of a variable being assigned the result of an [#Expression].
This is a statement telling the program to call a function with some arguments.
This is not a statement as the result is not used anywhere, this is just an [#Expression].
A compound statement is a collection of statements surrounded by braces.
This is a compound statement composed of two statements.
This is a compound statement with an
if condition, this is usually referred to as an "if statement".
This is not a compound statement, it's a chain of statements separated by commas. This form of chaining statements is considered bad practice.
An expression is a piece of syntax that yields a value, it's not a valid statement unless the yielded value is used in some way.
Expressions are often composed to form statements.
This is a simple addition expression that takes two values and applies the add operator to them.
Allman braces are preferred:
However, if you can't shake the muscle memory, K&R braces are also valid Pawn:
Switches must use two indent levels, one for the
switch block and another for each
case statement or compound statement.
Compound Statements (Blocks)
Blocks must always use braces, even if only a single line of code exists within a block. This applies to all levels including functions.
Functions must be named with
Global variables must always use
g prefixed PascalCase, so
gVariableName and should generally always be
Constant globals must use
Local variables must always use
camelCase and must never use single letter names, apart from:
k, etc in
z, etc in mathematical contexts
Enumerators, if named, must be prefixed with
E_ and use
SCREAMING_SNAKE_CASE. The one exception is when avoiding a
Index tag mismatch warning, in which case an
e_ prefix may be used.
SCREAMING_SNAKE_CASE must still be used even with the lower case
Enumerator fields must also be
SCREAMING_SNAKE_CASE and use the enumerator name as a prefix.
To avoid index tag warnings in some cases:
Enumerators must always be declared
static unless used outside the module.
Macros and Pre-Processor Definitions
Macros must always use
SCREAMING_SNAKE_CASE regardless of their usage.
Pre-Processor definitions (constant definitions) must also use
This helps differentiate between variables and constants as well as functions and macros.
It's generally advised to avoid inventing new syntactical elements in order to prevent confusion among newcomers as to which words are part of the language and which words are from libraries.
However, some older libraries do this and cannot change because of backwards compatibility.
Always document exported functions with a simple line comment in the format
// FunctionName does X, Y and Z and returns A where the first word is the name of the function itself followed by a brief description of what it does. No need to waste time describing each individual parameter. For example:
Each package should have a
README and, if necessary, each module should have a comment on the very first line describing what that module provides.