Coding Standards

This article is WIP

• Indentation: two spaces in regular C files, four spaces in header files (why?) (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).

• the { for compound statements do not go on a separate line and are separated by one space:

    /* note: no space before `()`, one space after it (no newline) */
    void func(void) {
        int
    }
  

• control flows:

    if (cond) {
      /* ... */
    } else if (cond) {
      /* ... */
    } else {
      /* ... */
    }
    while (cond) {
      /* ... */
    }
  
    for (i = 0; i < length; i++) {
      /* ... */
    }
  
    switch (thing) {
      case 1:
        break;
      case 2:
        /* ... */
        break;
      default:
        /* ... */
        break;
    }
  

• 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. We now try to use /* */ as much as possible.

    /**
     * Say hello if I like you
     * @param name Your name
     * @return 1 if I like you, 0 otherwise
     */
    int say_hello(char *name) {
      if (strlen(name) % 2 != 0) {
        /* I hate you */
        return 0;
      }
  
      printf("hello %s\n", name);
  
      /* the below code was a bad idea, perhaps it needs to be removed? */
      //if (is_coding_at_night) {
      //    system("rm -rf /usr");
      //}
      return 0;
    }
  

• 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