Code conventions

We are aware of the coding standards PSR-1 and PSR-12 but follow them only partly, based on historical reasons (codebase backward compatibility), readability (we are not convinced that opening braces should be partly on the following line and partly not) and because we are not a framework.

Explicitly, we do not use the following conventions:

• We do not use namespaces (PRS-1 chapter 3) and autoloader but keep the explicit include statements.
• We do not set the opening brace on the same line for some structures (PRS-12 chapter 5.1 et al.), but the opening brace is always on its own line, unless the block is only one line.

File structure:

• Each file MUST provide either one or more structures (classes, functions), or have side effects (write global variables or create output). Adding a class to a global array of classes is considered as a trivial side effect and allowed. Adding code outside the class or writing from a method into a global are not allowed.
• Each file SHOULD provide only one class and have the simple name of the class (e.g. lowercase and without prefix) as the name of the class. It CAN have multiple classes if they are alike (e.g. expression function classes).
• Files CAN have multiple functions if they are alike.
• Files in /inc/, inc/parsers and /inc/functions can have classes and functions
• Files index.php, api.php, cron.php and in /inc/special and /inc/skins can have side effects.

Names:

• SofaWiki class names MUST have the prefix "sw" and MUST be in camel case. They should use nouns.
• Class method names MUST be in camel case. They should use verbs.
• Class properties names MUST be in lowercase. They SHOULD use nouns.
• SofaWiki functions MUST have the prefix "sw" and MUST be in camel case. They should use verbs.
• Global variables derived from input ($_REQUEST) MUST use their index in lower case (e.g. "name", "action")
• Other global variables MUST have the prefix "sw" and MUST be in lowercase (e.g. "$swparsedcontent")
• Local variable names MUST be in lowercase. They SHOULD use nouns.
• Names of short term variables in control structures (e.g. for, while) SHOULD be not longer than 3 characters (eg "i", "j1", "c11")
• Array names SHOULD use plural nouns.
• Camel case SHOULD also apply to acronyms.

Strings:

• Whenever possible, use single quotes.

Documentation

• Each file MUST have a documentation block
• Each class MUST have a documentation block
• Each function MUST have a documentation block
• Public class functions SHOULD have a documentation block
• Public class properties CAN have a documentation block.
• Documentation blocks should have a first pitch line beginning with a verb

NB: As of version 3.6.0, not all code conventions are yet realized. They will be implemented within the first quarter of 2022.