Coding Standards

This article is WIP, please discuss at issue #554

• Indentation cluster: four spaces (not tabs, you can change the tab behavior on most editors to produce spaces when hitting TAB key)

• Keep it readable, use proper indentation, do not use excessive CAPS or question and exclamation marks.

• Watch your language, be nice for others.

• Try to stay within the 80 columns limit (especially comments).

• function definitions :

    # note: no space before `()`, one space after it (no newline)
    func() {
        local a="Use locals where possible"
        local b="do not use local a=x b=y"
        code
    }
  

• control flows:

    # small commands are allowed
    if single; then cmd; fi
    
    if condition; then
        one
    elif cond; then
        two
    else
        three
    fi
  
    while cond; do
        stuff
    done
  
    for ((i=0; i<$length; i++)); do
        echo "$i something"
    done
  
    case "$1" in
      1)# note: two spaces indentation
        anything
        ;;
      2)
        whatever
        ;;
      *)
        ;;
    esac
  

• Comments: try to explain a code block if it needs to (examples of useless comments). Try to separate code blocks with a newline. Regular comments should have a space after the #, disabled code should have no extra space after it.

    # turns on the graphical card and loads the driver if necessary
    bumblebee-enablecard
  
    # check if optirun is already running
    if pidof -x /usr/bin/optirun >/dev/null ; then
        echo "Already running"
    fi
  
    # the below code was a bad idea, perhaps it needs to be removed?
    #if is_coding_at_night; then
    #    rm -rf /usr
    #fi
  

• Commits: Keep the commit message within 72 characters, split over lines if necessary. Use the first line for a short summary.

    Fixed data loss bug
  
    (optional additional description)
  
    - Fixed a bug which could lead to data loss if it's night and the user 
    about to commit some changes (Closes: GH-123)
  
    - Removed obsolete references to Prime-NG (GH-554: Clean Up)
  

  Note the use of GH-<number>, it links to an issue. If it's Closes: GH-<number>, it also closes issue <number>. An extra newline should exist between every new line.

• Commits (2): don't create God commits: commits with a lot of modifications. Split changes. git-gui is a great tool for staging changes.

• PPA Changelog : The changelog for PPA releases should contain relevant details. Our users are not interested in a version number, but in the changes:

    PACKAGE (VERSION) UNRELEASED; urgency=low
  
      * New upstream release.
        - Message based on git changelog, that's why we expand it right?
        - Fix a bug which could lead to data loss (GH-123)
      * Main point (mind the two spaces in front of it)
        - some clarification (mind the four spaces in front of it)
        - we do not need to include all changes here, especially changes to whitespace
  
     -- User Name <[email protected]>  Thu, 04 Aug 2011 10:34:35 +0200