Coding Standards

Lekensteyn edited this page Jan 19, 2012 · 8 revisions

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 <name@example.com>  Thu, 04 Aug 2011 10:34:35 +0200