coding.txt

Hello Popeye-Hackers!

The text below was created by Elmar Bartel (ElB) with some
annotations by myself (NG).


I was in need to correct the implementation of the 3:6 leaper.
In trying to do so, I took a look at the sources of popeye and
was astonished to see a wild mixture of coding styles. After a
short conversation with Norbert I took the time and reedited all
of the source files, to make them appear under a common coding
style. 

I know from my own experience, that it is not a nice feeling
to read code that sometimes ago looked familiar, but is now in a
complete different shape. But I also learned to value a consistent
coding style when browsing code of others: after a short time
of getting used to it, it gets easier and quicker to understand
what the code is intented to do.

I am pretty confident, that I didn't break the code. All examples
are done with the same output as before my changes. But nobody is
perfect! I may have introduced a very subtle error that slipped
through all the tests; so take this with a little bit grain of salt.

Please don't blame me for changing the style in a way, that is
completely unacceptable to you. I don't believe this is true,
but in that case, go ahead and change it again to what you like
better. Please, do it then consistently over ALL the source 
without breaking the code :-)


Finally here are some remarks on what I did:

Editing:
  There seemed to be no joint agreement on what number of spaces
  to set hard tabs in the files. If hard tabs are used, then it
  should be assumed, one hard tab moves forward to the next position
  that is a multiple of 8. I regard it as a bad idea to set tabstop=4.
  Please, either stick with 8, or use no tabs at all.

Indentation:
  I used an indentlevel of four spaces.
  This amount of indentation is enough to be recognized after several
  lines, yet small enough to allow for several indent levels.

Long Lines:
  I tried to break the lines before the 72 character. 
  You may ask why 72. The reason is that it proved as nice value.
   . longer lines are much less understandable.
   . on a standard xterm with 80 columns I can use linenumbers
     in vi without wrapping the lines.
  (NG) Fortunately, ElB didn't succeed in cutting all lines to
       length 72. I see this a little bit more relaxed, but 
       it would be nice if you keep them below 120 ...

Statements:
  General rule: one statement one line.
  It proofed very misleading in reading code, when there are
  unexpectedly more than one statement on a line. This occured on
  very few places in the popeye sources.

Braces:
  All compound statements (if, do, while, for) normally have their
  opening braces on the same line. The closing brace is lined up
  with the starting letter of the statement and is placed alone on
  a sperate line.
  When the line gets too long and has to be broken, the opening brace
  is lined up with the starting column of the statement and is put
  alone on a seperate line.

Breakup of expressions:
  When I had to break expressions, I always tried to start the line
  with an indented operator. This way it is always clear that the previous
  line is not finished. The indentation used then is 2 blanks. The
  expection are if-clauses, where I also started with an operator, but
  indented as much as to lineup the same binding level of the boolean
  operators.

Breakup of long function declarations:
  Each parameter of the function gets its own line.
  This gives room even for function parameters to fit on one line.
  The starting brace of the function body is then placed in the begin
  of lines.

Coding of special C-constructs:

 + if-clauses:
   . I don't use assignments in the if clause.
   . If used, I always used parenthesis for the assignment expression:
      Not:
      	if (ret = i2 == k)
      At least:
      	if (ret = (i2 == k))
      Preferred:
      	ret= i2 == k;
	if (ret)

      Not:
	if (a=func())
      But:
      	if ((a=func))

    Reason: this allows the compiler detect places
    where '==' was meant and '=' was coded instead.

    More prefereble for me is to write
      	a=func()
	if (a) {
	}
    Reason: lines are shorter, hence easier to read.

    Bad Example:
      if (flag= ooorphancheck(olist[k], p == orphanb ? -*porph : *porph, -p, evaluate))
    I have rewritten this line:
      if (p==orphanb)
	  op = -*porph;
      else
	  op = *porph;
      flag = ooorphancheck(olist[k], op, -p, evaluate);
      if (flag) {
      	  ...
      }

 + I use always braces for code in 'then' or 'else' clauses.
   Only simple assignements should be an exception, but not when
   occuring in cascading if-then-else. Good habit is always to
   use braces.

 + Empty loops:
   I always write them with ';' on a single line, to make very clear
   an empty loop body is intended.

 + Boolean expressions grow often very long.
   . here I use most of the time parentheses and do NOT rely
     on operator binding
  	Example:
	NOT: a && b || c
	BUT: a && (b || c)

 + When using macros to do some statements, I use the
        do { statements } while (0)
   construct. This way the terminating ';'  can be used.

 + I don't use parenthesis on return values.
   	NOT: return(false);
	BUT: return false;
   Return is not a function call, but a special statement; writing
   it the first way, it is easily confused with a function call.
   In my editor I've some shortcuts to position me to the next
   function call; but I am sure there are other occasions.

 + I don't use '^' operator in boolean expression.
   '^' is a bitwise operator and not a boolean operator.
   It works only correct if the values on one bit position are
   used. In boolean expressions it can be replaced with the != operator.

 + When there were long expressions for if conditions,
   I needed to break them over several lines.
   Then I tried to use the next binding operator to start the line with
   and indent, if the expression belongs to another level in the
   expression. I placed the opening brace for the 'then' clause below
   the 'if', to mark where the conditions stops.
   Example:
        if (rex_circe
            && (CondFlag[pwc]
                || e[(*circerenai)
                     (e[rn], spec[rn], rn, initsquare, blanc)] == vide))
        {
            return false;
        }