standards: Formatting

1 
1 5.1 Formatting Your Source Code
1 ===============================
1 
1 Please keep the length of source lines to 79 characters or less, for
1 maximum readability in the widest range of environments.
1 
1    It is important to put the open-brace that starts the body of a C
1 function in column one, so that they will start a defun.  Several tools
1 look for open-braces in column one to find the beginnings of C
1 functions.  These tools will not work on code not formatted that way.
1 
1    Avoid putting open-brace, open-parenthesis or open-bracket in column
1 one when they are inside a function, so that they won't start a defun.
1 The open-brace that starts a 'struct' body can go in column one if you
1 find it useful to treat that definition as a defun.
1 
1    It is also important for function definitions to start the name of
1 the function in column one.  This helps people to search for function
1 definitions, and may also help certain tools recognize them.  Thus,
1 using Standard C syntax, the format is this:
1 
1      static char *
1      concat (char *s1, char *s2)
1      {
1        ...
1      }
1 
1 or, if you want to use traditional C syntax, format the definition like
1 this:
1 
1      static char *
1      concat (s1, s2)        /* Name starts in column one here */
1           char *s1, *s2;
1      {                     /* Open brace in column one here */
1        ...
1      }
1 
1    In Standard C, if the arguments don't fit nicely on one line, split
1 it like this:
1 
1      int
1      lots_of_args (int an_integer, long a_long, short a_short,
1                    double a_double, float a_float)
1      ...
1 
1    For 'struct' and 'enum' types, likewise put the braces in column one,
1 unless the whole contents fits on one line:
1 
1      struct foo
1      {
1        int a, b;
1      }
1 or
1      struct foo { int a, b; }
1 
1    The rest of this section gives our recommendations for other aspects
1 of C formatting style, which is also the default style of the 'indent'
1 program in version 1.2 and newer.  It corresponds to the options
1 
1      -nbad -bap -nbc -bbo -bl -bli2 -bls -ncdb -nce -cp1 -cs -di2
1      -ndj -nfc1 -nfca -hnl -i2 -ip5 -lp -pcs -psl -nsc -nsob
1 
1    We don't think of these recommendations as requirements, because it
1 causes no problems for users if two different programs have different
1 formatting styles.
1 
1    But whatever style you use, please use it consistently, since a
1 mixture of styles within one program tends to look ugly.  If you are
1 contributing changes to an existing program, please follow the style of
1 that program.
1 
1    For the body of the function, our recommended style looks like this:
1 
1      if (x < foo (y, z))
1        haha = bar[4] + 5;
1      else
1        {
1          while (z)
1            {
1              haha += foo (z, z);
1              z--;
1            }
1          return ++x + bar ();
1        }
1 
1    We find it easier to read a program when it has spaces before the
1 open-parentheses and after the commas.  Especially after the commas.
1 
1    When you split an expression into multiple lines, split it before an
1 operator, not after one.  Here is the right way:
1 
1      if (foo_this_is_long && bar > win (x, y, z)
1          && remaining_condition)
1 
1    Try to avoid having two operators of different precedence at the same
1 level of indentation.  For example, don't write this:
1 
1      mode = (inmode[j] == VOIDmode
1              || GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])
1              ? outmode[j] : inmode[j]);
1 
1    Instead, use extra parentheses so that the indentation shows the
1 nesting:
1 
1      mode = ((inmode[j] == VOIDmode
1               || (GET_MODE_SIZE (outmode[j]) > GET_MODE_SIZE (inmode[j])))
1              ? outmode[j] : inmode[j]);
1 
1    Insert extra parentheses so that Emacs will indent the code properly.
1 For example, the following indentation looks nice if you do it by hand,
1 
1      v = rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
1          + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000;
1 
1 but Emacs would alter it.  Adding a set of parentheses produces
1 something that looks equally nice, and which Emacs will preserve:
1 
1      v = (rup->ru_utime.tv_sec*1000 + rup->ru_utime.tv_usec/1000
1           + rup->ru_stime.tv_sec*1000 + rup->ru_stime.tv_usec/1000);
1 
1    Format do-while statements like this:
1 
1      do
1        {
1          a = foo (a);
1        }
1      while (a > 0);
1 
1    Please use formfeed characters (control-L) to divide the program into
1 pages at logical places (but not within a function).  It does not matter
1 just how long the pages are, since they do not have to fit on a printed
1 page.  The formfeeds should appear alone on lines by themselves.
1