Developer Guidelines

In order to reduce stress, grey hair, and other health issues developers implementing any type of feature, bug fix, or creating code that will be part of the Software Developer Kit (SDK) should follow the guidelines and best practices below.

Guidelines & Best Practices

• Always aim for code readability over brevity
• Use clear commit messages for git and for all function / class method comments
• Include @params, @return, {datatype}, for all functions / class methods where applicable
• Use at least 2 space between functions / class methods for code readability
• Never commit node_modules, vendor, or other package content installed by a package manager -- just include the file that shows dependencies (i.e.: package.json for Node, composer.json for PHP)
• Never commit system files (i.e.: .DS_Store on MacOS)
• Don't let text exceed roughly 77-80 columns if it can be avoided (merely for code readability on GitHub and small screen devices others may be developing on). Use the word wrap feature on your IDE / text editor to help with this.
• Never push code breaking changes to master, always use a separate branch

Examples of Bad v. Good Practices

Code readability

    // BAD PRACTICES
    const airport   = 'KHOU';
    let ac          = 'Boeing 747';

    getPos();
    gPos();
    gACPosition();

    // BETTER PRACTICES
    const AIRPORT   = 'KHOU'; // constants use all caps
    let aircraft    = 'Boeing 747';

    getAircraftPosition();

Commit messages

    # BAD PRACTICES (even I (Drew) am guilty of)
    "Made some changes..."
    ":)"
    "Saving..."
    "Saving progress"
    "Update some stuff"

    # BETTER PRACTICES
    # Note how the message is prefixed with a keyword

    "Bug Fix: Fixed AssetLoader.getAll() method throwing null instead of returning object."
    "Feature: [Your detailed message here about a new feature added]"
    "Update: [Your detailed message here; your next detailed message here]"

We propose prefixing the following keywords to your commit messages to help with debugging and tracking down changes made overtime: Bug Fix, Feature, Update, Removed

Code comments

    // BAD PRACTICES
    
    // sets the position of the aircraft
    function setAicraftPosition(aircraft, lat, long, orientation) {
        . . .
    }


    // BETTER PRACTICES

    /**
     * Sets the position of a given aircraft
     * @param {integer} aircraft - the aircraft which you wish to change position
     * @param {float} lat - the desired latitude to set
     * @param {float} long - the desired longitude to set
     * @return {boolean} - returns true if position set
     */
    function setAircraftPosition(aircraft, lat, long, orientation) {
        . . .
    }