Style Guidelines for fptools

Comments

These coding style guidelines are mainly intended for use in rts.

NB These are just suggestions. They're not set in stone. Some of them are probably misguided. If you disagree with them, feel free to modify this document (and make your commit message reasonably informative) or mail someone (eg. The GHC mailing list)

References

If you haven't read them already, you might like to check the following. Where they conflict with our suggestions, they're probably right.

Portability issues

Debugging/robustness tricks

Anyone who has tried to debug a garbage collector or code generator will tell you: "If a program is going to crash, it should crash as soon, as noisily and as often as possible." There's nothing worse than trying to find a bug which only shows up when running GHC on itself and doesn't manifest itself until 10 seconds after the actual cause of the problem.

We put all our debugging code inside #if defined(DEBUG). The general policy is we don't ship code with debugging checks and assertions in it, but we do run with those checks in place when developing and testing. Anything inside #if defined(DEBUG) should not slow down the code by more than a factor of 2.

We also have more expensive "sanity checking" code for hardcore debugging - this can slow down the code by a large factor, but is only enabled on demand by a command-line flag. General sanity checking in the RTS is currently enabled with the -DS RTS flag.

There are a number of RTS flags which control debugging output and sanity checking in various parts of the system when DEBUG is defined. For example, to get the scheduler to be verbose about what it is doing, you would say +RTS -Ds -RTS. See rts/include/RtsFlags.h and rts/RtsFlags.c for the full set of debugging flags. To check one of these flags in the code, write:

  IF_DEBUG(gc, fprintf(stderr, "..."));
would check the gc flag before generating the output (and the code is removed altogether if DEBUG is not defined).

All debugging output should go to stderr.

Particular guidelines for writing robust code:

Syntactic details

CVS issues

Commandline arguments

A program in fptools should try follow the following rules for commandline arguments: When an unknown commandline argument is encountered, the program should display usage information on stderr and exit unsuccessfully.