1. Coding Standard

This section explains how one should write and maintain code in development environment. Some coding principles may differ from one to another in diffrent tech stack but basic idology remains the same and we encourage you to follow the conventions throughout.

PSR Compliance

All PHP code MUST follow PSR guidelines. Most likely your project's server side is based on LAMP stack and uses Laravel as core framework. Since Laravel follows PSR-2 we like to stick to it and expect you to follow the same guidelines in most of PHP development environments.

We strongly recommend that all code MUST comply with PSR-1, PSR-2, PSR-4 standards. Make sure you read through the mentioned PSR guidelines.

1.1 Naming conventions

Variables, Methods, Properties, Constants

Variable, method and class property names MUST be written in camelCase.

// Single word variables
$user = new User();
$data = getSomeData();

// Multi-word variables
$authenticatedUser = getLoggedInUser();
$photoSubmissions = [....];

// Class properties
Class Person {
  public $firstName;
  public $age;
}

Constant names MUST be written in UPPERCASE. Words can be separated by underscores. Use the underscore to group constants thematically.
```
STUFF_LEVEL
COOLNESS_FACTOR
PATTERN_MATCH_EMAILADDRESS
PATTERN_MATCH_VALIDHTMLTAGS
```

Names MUST be self-explanatory not shortened beyond recognition, but rather longer if it makes their meaning clearer

//Correct naming of variables
$singletonObjectsRegistry
$argumentsArray
$aLotOfHtmlCode

//Incorrect naming of variables
$sObjRgstry
$argArr
$cx

Only the characters a-z, A-Z and 0-9 are allowed for names. Don't use special characters.

Namespace, Class, Interface, Trait, Exception

Class and interface files are named according to the class or interface they represent.

Interface names must be adjectives or nouns and have the Interface suffix.

\Aws\AwsClientInterface.php
\MyCompany\MyPackage\MyObject\MySubObjectInterface

Exceptions should reside in their own sub-namespace end with the word Exception.
```
\Aws\AutoScaling\Exception\AutoScalingException
\MyApp\Coffee\Exception\OutOfCoffeeException
```
- Trait names must be adjectives or something that signifies what it does.
```
use Notifiable;
use CanResetPassword;
```
Each file must contain only one class, interface or trait.
File/Directory names MUST be declared in StudlyCase.

1.2 Styling & Formatting

Refer to PSR-2 standard.

1.3 Commenting/Documenting Code

All comments should be written in English, and should in a clear way describe the commented block of code. We follow PhpDoc standard to mantain code documentation as much as possible.

Comments can include phpDocumentor tags.

A file contains different documentation blocks, relating to the class in the file and the members of the class. A documentation block is always used for the entity it precedes.

/**
 * First sentence is short description. Then you can write more, just as you like
 *
 * Here may follow some detailed description about what the class is for.
 *
 * Paragraphs are separated by an empty line.
 */
 class SomeClass {
 
   /**
    * A short description, very much recommended
    *
    * @var string
    */
    protected $title = 'Untitled';
    
    
    /**
     * A description for this method
     *
     * Paragraphs are separated by an empty line.
     *
     * @param \Model\Post $post A post
     * @param string $someString This parameter should contain some string
     * @return void
     */
    public function addStringToPost(\Model\Post $post, $someString) {
     ...
    }
  }

In general you should try to code in a way that the types can be derived (e.g. by using type hints and annotations) to increase readability and to activate auto-completion and syntax-highlighting.

2. Development Process

3. Version Control

3.1 Branching

master branch reflects production.
Pull develop and checkout a new branch to start working on a feature or fix;
Feature branches MUST be named as feature/{feature-name}
Issue fixing branches MUST be named as fix/{issue-name}
Hot fix branches MUST be named as hotfix/{issue-name}. To perform hotfix, you MUST checkout to master and create a new hotfix branch there.

3.2 Commits

Commits SHOULD be made for every significant change in the codebase.

Each commit SHOULD address one and only one concern at a time.

# Wrong
Fix errors on search page and add loader

# Correct
Fix errors on search page
Add loader when awating search result

Commit subjects SHOULD be short and reflect the upcoming change.
Capitalize the subject line.

Use the imperative mood in the subject line.

# Wrong
Added loader when awating search result

# Correct
Add loader when awating search result

Do not end the subject line with a period.

# Wrong
Open the pod bay doors.

# Correct
Open the pod bay doors

Follow Conventional Commits guidelines to explicitly specify the commit type.

FIX: Resolve errors on search page
FEAT: Add loader when awating search result

whoisdevd/Guidelines.md