Skip to content

Latest commit

 

History

History
180 lines (150 loc) · 6.16 KB

code_standards.md

File metadata and controls

180 lines (150 loc) · 6.16 KB
Raw

Project Code Standards

Author: Chris Zuber
Created: 2015-01-01
Modified: 2014-01-02

Overview

Please see

The purpose of this document is to apply the specifications as stated by PHP-FIG with as little alteration as necessary in order to provide better compatibility with autoloaders such as spl_autoload() natively in PHP as well as provided by Composer.

This document also aims to correct the grammar used — E.G. curly braces SHALL be placed on a new line after function declarations rather than MUST as defined in Terminology.

It is not meant to compete against any PSR given by PHP-FIG, but rather to address the same issues under different circumstances.

Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

I make the following exception to distinguish between SHALL and MUST:

  • MUST, MUST NOT, and REQUIRED signify that the reason is functional and to ensure compatibility.
  • SHALL and SHALL NOT mean that, while still a requirement, the reason is preference rather than pure necessity.

Naming Things

∙ Files

Files MUST be named such that they are compatible on all Operating Systems. They SHALL contain all lower case or all upper case alpha-numeric characters, and underscores in their names.
Names SHOULD be all lower case, except for those which are automatically generated and/or are of special significance such as README.md
All files SHOULD have a name portion, except for files of special significance such as .htaccess
All extensions MUST be preceded by a ., SHALL be lower case and alpha-numeric only, and SHOULD NOT have a depth greater than two extensions. They SHALL NOT contain special characters, spaces, or a combination of upper and lower case characters. They SHOULD contain one or two extension as appropriate to the mime-type.
([A-Z\d_]+|[a-z\d_]+)?(\.[a-z\d]+){0,2}

∙ Functions

Functions SHALL contain at minimal documentation as defined in Documentation containing a brief description, a list of parameters including type along with a description, and the return including type.

Any function not accepting parameters or without a return should declare void for these.

    /**
     * {my_fucntion description}
     *
     * @param array                 $array   [{description}]
     * @param string                $string  [{description}]
     * @param bool                  $bool    [{description}]
     * @param int                   $int     [{description}]
     * @param float                 $float   [{description}]
     * @param \vendor\package\class $class   [{description}]
     *
     * @return {type}                        [{description}]
     */
    function my_function(
            array $array = [],
            $string = '',
            $bool = false,
            $int = 9000,
            $float = 3.14,
            \vendor\package\class $class
    )
    {
        //Function code... Do stuff
        return $results;
    }

    /**
     * {second_function description}
     *
     * @param void
     * @return void
     */
    function second_function()
    {
        \\Do Stuff
    }

Functions SHALL be named in all lower case, with words separated by _ [a-z\d]+(_[a-z\d]+)*

Functions SHALL maintain as small a scope as necessary. Specifically, functions SHALL NOT make use of

  • global
  • $_GLOBALS
  • $_REQUEST
  • $_SESSION
  • $_COOKIE

unless that is their sole purpose.

Any function of sufficient complexity SHOULD use array_(map|filter|walk) in favor of foreach for loops, using use() as necessary.

∙ Namespaces

Classes SHOULD contain only lowercase alpha-numeric characters and underscores aside from namespace separators </q> unless you are willing to update your composer.json or other autoloader configuration file with every new class/namespace to accomodate the lower case file name requirement.
(\[a-z\d_]+)+

This is for best compatibility between autoloaders since spl_autoload loads files from include_path as lower case, whereas Composer is case sensitive. In order for namespaces to work with both, namepspaces are required to be entirely lower case.

Code Format

Limiting component scope

Documentation

Images, Fonts, & other Media

All images, fonts, and other forms of media MUST use Creative Commons or similar license allowing adaption, modification, and redistribution.

Minimal Class Structure

Class Doc Comments MUST be included after namespace declaration. This is to ensure compatibility with ReflectionClass.

All method documentation SHALL include at minimal

  • Method description
  • @param
  • @return
namespace {namespace};
/**
 * {Class description}
 *
 * @author {First} {Last} <{user@example.com}>
 * @package {similar to namespace}
 * @version {semantic version, E.G. 1.2.3}
 * @copyright {YYYY}, {First} {Last}
 * @license {GPL-3 compatible license}
 */
[final|abstract] (class|interface|trait) {classname} [extends {child class}] [implements {interface}]
{
    /**
     * {method description}
     * @param {type}    [{description}]
     * @return {type}   [{description}]
     */
    [final] {visibility} {method name}([type hint [param[ = {default value}]]])
    {
        // Method code
    }
}

Contributing