Developers Documentation

×

Warning

301 error for file:https://clearos.com/dokuwiki2/lib/exe/css.php?t=dokuwiki&tseed=82873f9c9a1f5784b951644363f20ef8

User Tools

Site Tools


Framework Coding Standards Start

For ClearOS apps, consistent source code styles are (ahem) strongly encouraged. The document is inspired by the PEAR Coding Standards as well as the CodeIgniter Style Guide.

Documentation

Every source code page should start with the phpDoc Header Documentation. Class files (libraries and controllers) should be documented a similar way.

License Notice

A License Notice should appear just below the documentation. Most licenses have their own templates, so feel free to follow those standards.

Indenting and Whitespace

  • Use 4 spaces for indenting (no tabs)
  • Lines should be no longer than 150 characters (120 characters is better, but long translation tags can make this a bit onerous)

Here are the vim rules 4 space indentation:

set expandtab
set shiftwidth=4
set softtabstop=4
set tabstop=4

Strings

Use single quotes unless you need to parse a variable or want to avoid messy escape characters.

// Valid
$example = 'This is valid.';
$example = "SELECT id FROM users WHERE username = 'thorton'";
 
// Invalid
$example = "This is invalid.";
$example = 'SELECT id FROM users WHERE username = \'thorton\''; // messy

Control Structures

Control structures (if, while, for etc.) should have one space between the keyword and the opening parentheses. If it improves readability, feel free to drop the parentheses when they are optional.

if ($example === '1') {
    // Do something 
} elseif ($other === '2') {
    // Do something
} 

If you need to split a long if statement into multiple lines, use your best judgement to make it as readable as you can. If you need to add a couple of microseconds to handle an extra variable declaration, then do if it makes the code that much more readable.

Function Calls

Function calls should be called with no spaces between the function name and the opening parentheses.

$example = foo($bar);

Library Definitions

class Posix_User($username)
{
    // code 
}

Static Methods

Please be careful when making the decision to declare a method static. If you think the method may need to change to non-static in the future, then declare it non-static today. Static methods are appropriate for simple calculations (for example, calculating a Windows NT password).

Naming Conventions

Methods

Methods use lower case and underscores between words. Examples:

  • get_workgroup()
  • get_dns_server()
  • set_domain($domain)
  • _load_config()

Public

All public methods should use the keyword public (even though this is optional in PHP). Examples:

  • public function get_workgroup()
  • public function set_domain($domain)

Private/Protected

All private and protected methods should be prefixed with an underscore. Only methods that a truly private should be marked as private. Examples:

  • protected function _load_config()
  • private function _calculate_something($source)

Friend

In some cases, you may want to declare a method that is essentially private, but can be used by another class. For example, the Group class has a method called convert_ldap_attributes. The Group_Manager class (which can return a list of groups with detailed information) also needs access to this method in the Group class. Since PHP does not include friend class support, we use the public method naming convention, but hide it in the API documentation (@ access private in phpDocs).

/**
 * Converts LDAP attributes to group metadata.
 *
 * ... snip .... 
 * @access private
 */
 
public function convert_ldap_attributes($attributes)
{

Constants

Constants should be all upper case with underscores.

  • FILE_xyz - the full path name of a regular file
  • COMMAND_xyz - the full path name of an executable file
  • STATUS_xyz - a status level

TRUE, FALSE and NULL

TRUE, FALSE and NULL are constants and should also be in upper case.

Error and Exception Handling

Logging Levels

Four error/exception logging levels are used in ClearOS.

LevelConstantDescription
ErrorCLEAROS_ERRORFatal error or exception messages
WarningCLEAROS_WARNINGNot fatal, but serious enough to log
InfoCLEAROS_INFOInformational messages
DebugCLEAROS_DEBUGDebug and profiling messages

The CLEAROS_INFO log level is typically used for logging audit data, e.g. “user X changed their password”. The CLEAROS_WARNING log level is not used very much. Typically, you only see this level for highlighting deprecated behavior in a log file.

Exceptions

The base PHP Exception class uses CamelCase. This is a bit problematic since ClearOS coding standards require lower case method names. Instead of littering the code base with non-standard $e→getMessage() calls, the global function clearos_exception_message should be used instead. Here's an example:

try {

  // Do some stuff here

} catch (File_Not_Found_Exception $e) {

  // Not fatal in this case

} catch (Exception $e) {

  throw new Engine_Exception(clearos_exception_message($e), CLEAROS_ERROR);

}

content/en_us/dev_framework_coding_standards_start.txt · Last modified: 2015/03/01 15:46 (external edit)

https://clearos.com/dokuwiki2/lib/exe/indexer.php?id=content%3Aen_us%3Adev_framework_coding_standards_start&1710826539