Standards & Practices

This page describes the general standards & practices to follow when programming with Vanilla.

Content Format

All data and files should be saved in UTF-8 encoding. We've made our database structure class default to this formatting, and we recommend that you encode all files in this format as well. Failure to follow this standard will result in characters being rendered improperly, and these issues can be extremely difficult to fix.

PHP Opening & Closing Tags

Never use short-form PHP opening tags, instead always using <?PHP
Vanilla files do not include the PHP closing tag as it is optional to the parser and can cause bugs when used incorrectly.

Classes, Methods, Properties, and Variables

Classes, method names, and variables are all CamelCased. Do not separate multiple words with underscores. Methods should be explicitly declared as static, private, protected, or public. All of the names should describe their purpose, not use abbreviations, and be a reasonable length. Single-letter variables should only be used in for loops.

Correct

class MyClassName {

    var $MyProperty;

    public function MyPublicMethod() {

        $Variable = TRUE;

    }

    protected function MyProtectedMethod() {}

}

Incorrect

class myClassNameIsFarTooLongForItsOwnGood {

    var $my_Property;

    function my_public_method() {

        $variable = TRUE;

    }

    function My_Other_Method() {}

}

Exception: Vanilla uses underscores as a special character that helps the PluginManager to identify classes, methods, and actions. Any class in that implements Gdn_IPlugin may contain underscores in method names for this purpose. The format is as follows:

public function ClassNameToAttachTo_MethodOrEventNameToReference_Action(&$Sender) {

    // Do something awesome.

}

For more information on Plugins and their use of underscores, read the Plugin Quick-Start guide.

Commenting

All functions and methods should be documented using PHP Doc syntax. Comments should be used within complex chunks of code to help others understand the functionality. Where applicable, leave a single blank line between code and single-line comments to ease readability. Wrap long comments around 70 characters to maintain readability.

Constants

Native PHP constants like TRUE, FALSE, and NULL should always be uppercase. Constants should be written in upper case and use underscores to separate words.

Correct

MY_CONSTANT_NAME

Incorrect

myConstantName

Files & Naming Conventions

To prevent name clashes, we've prefixed all vanilla/garden classes with Gdn_. Similarly, your application and plugin classes should be prefixed with a relevant string. You should never have more than one class definition in a single file, and your file should be named similar to the class, but always in lower case. In Vanilla/Garden we've gone so far as to identify the contents of files with prefixes: "class", "functions", and "interface" are used to help identify the contents of the files.

Code Indenting

Opening braces should be on the same line as the control statement that opened them.

function MyFunction() {

}

for ($i = 0; $i < 10; ++$i) {

}

Function or method calls with a large number of arguments can be wrapped and indented with one argument per line.

BigFunctionCall(

    $Arg1,

    $Arg2,

    $Arg3,

    $Argn

);

An indent is 3 spaces, never a tab.