Coding Guidelines

These standards for code formatting and documentation must be followed by anyone contributing to OpenMediaVault. Any contributions that do not meet these guidelines will not be accepted.

Indentation
Use 4 space tabs for writing your code. If you are modifying someone else's code, try to keep the coding style similar.

Line Length
Lines shouldn't be longer than 80 characters.

Line Endings
Line endings should be Unix-style LF.

Encoding
Files should be saved with UTF-8 encoding.

Classes
Class names should start with OMV.

/** * @class OMVSystem */ class OMVSystem { ... }

/** * @class OMVStorageDevices * @extends OMVObject */ class OMVStorageDevices extends OMVObject { ... }

This naming convention must be ignored for RPC classes.

Functions/Methods
Functions/Methods must use camel case syntax, this convention capitalizes the first character of each word except the first one.

public function getGecos { ... }

public function getHomeDirectory { ... }

Variables
Variables must use camel case syntax, this convention capitalizes the first character of each word except the first one.

$fsName $outputFileName

Constants
Constants should start with OMV_ and should be all upper case.

$OMV_DEFAULT_FILE = "/etc/default/openmediavault"; $OMV_JSONSCHEMA_SORTFIELD = '"type":["string","null"]';

Arrays
Array keys must be in lower case.

$object = array( "uuid" => OMVUtil::uuid,  "name" => $data['name'],  "email" => $data['email'],  "disallowusermod" => array_boolval($data, "disallowusermod"));

$object = array( "name" => $raid->getName,  "devicefile" => $raid->getDeviceFile,  "level" => $raid->getLevel,  "numdevices" => $raid->getNumDevices,  "devices" => $raid->getDevices);

Multiline parameters
Functions with many parameters may need to be split onto several lines to keep the 80 characters/line limit. The first parameters may be put onto the same line as the function name if there is enough space. Subsequent parameters on following lines are to be indented 2 spaces.

throw new OMVException(OMVErrorMsg::E_EXEC_FAILED, $cmd, implode("\n", $output));

$dispatcher->notify(($data['uuid'] == $GLOBALS['OMV_UUID_UNDEFINED']) ? OMV_NOTIFY_CREATE : OMV_NOTIFY_MODIFY,  "org.openmediavault.system.storage.hdparm", $object);

Control Structures
for (i = 0; i < 10; i++) { if (foo(i)) { bar; } }

switch (x) { case 'a': ...   break; case "b": ...   break; default: ...   break; }

if (a) { foo; } else { bar; }

if (TRUE === $result) break;

foreach ($output as $outputk => $outputv) { foo; }

Single line comments
You should use the // comment style to "comment out" code. It may be used for commenting sections of code too.

Single line comments must be indented to the indent level when they are used for code documentation.

Block comments
Block comments should usually be avoided. For descriptions use the // comments.

// Parse output: // shadow:x:42:openmediavault // snmp:x:112: // sambashare:x:113: // openmediavault:x:999: // nut:x:114: foreach ($output as $outputv) { ... }

Documentation comments
Use the doxygen syntax where possible.

/** * Get the filesystem label. * @return The filesystem label, otherwise FALSE. */ public function getLabel { ... }

/** * Enumerate all disk devices on the system. * @return An array containing physical disk device objects with the *  fields \em devicename, \em devicefile, \em model, \em size, *  \em description, \em vendor, \em serialnumber, \em israid and *  \em isrootdevice. */ public function enumerateDevices { ... }

/** * Enumerate all disk devices on the system. The field \em hdparm will be * added to the hard disk objects if there exists additional hard disk * parameters (e.g. S.M.A.R.T. or AAM) that can be defined individually * per hard disk. * @param data An array containing the following fields: *  \em start The index where to start. *  \em limit The number of objects to process. *  \em sortfield The name of the column used to sort. *  \em sortdir The sort direction, ASC or DESC. * @return An array containing the requested objects. The field \em total *  contains the total number of objects, \em data contains the object *  array. An exception will be thrown in case of an error. */ public function getList($data) { ... }