= Various conventions for Jhc coding =

== internal naming ==

for a variety of reasons, the compiler needs to generate Haskell names
internally, the convention is that internally generated names are in a
pseudo-module that ends in '@' so it cannot conflict with any real module.
the name immediately after the module name MUST start with a lower case letter
so the module name can be unambiguously recovered. the convention is to prepend
an 'f' to names that start with a capital letter.

* Instance@ - contains the implementation of all instance methods and the
   defaults for classes.

* LL@ - these are generated by lambda lifting functions to the top level.

* W@ - this is the worker of a worker/wrapper split.

* X@ - various temporary names generated from existing names

* Jhc@ - A finite set of built in special names that never occur in haskell
source. These are enumerated in Name.Names

* F@ - bindings that have been floated out of top level definitions

* A@ - bindings created by atomization of arguments

* Spec@ - specializations of polymorphic functions

* TP@ - non type-erased version of function in case it was passed as an
  argument to a rank-n function.

* FE@ - "foreign export" stub

when a name is one of several generated from an existing one, the convention
is to append '$n' for some number that makes the name unique.

for example the third function lambda lifted out of Main.foo would be named
LL@.fMain.foo$3

some generated names inside the front end do not follow this convention due
to historical reasons or because the fully qualified name is not available or
expected. such names should contain '@' to avoid conflict with any Haskell
name.

non top-level names are made unique in the front end by prepending a number
and an underscore to them. since Haskell does not allow names to start with a
number, these can never conflict with top-levels.


== Jhc source language ==

the C preprocessor should be avoided whenever possible, it should actually
never be needed.

Jhc is never targeted towards a particular architecture or bitwidth, any
compiled version of Jhc running on any architecture should be able to produce
code for any backend or architecture so no arch-dependent ifdefs or hardcoding
of type sizes. Jhc itself should be entirely portable and produce identical
results for identical target arches no matter what it is running on. (among
other reasons, so we may cross-compile to embedded architectures and to aid in
bootstrapping)

non-literate sources are preferred to literate sources. Correct haddock style
comments should be included liberally, even for non-exported functions.

The most recent released version of GHC Haskell is to be targeted. no need to
not use the latest features or provide ifdefs for backwards compatibility.
However one should not use extensions without good reason and certain ones
(implicit parameters) should never be used as they are broken.

mutually recursive modules are too be generally avoided unless doing so would
compromise code modularity and readability. a refactoring into multiple
modules to avoid the recursion should be preferred when possible, but a
logical layout of the module hierachy takes precidence.


== code style ==

* lines should have no trailing whitespace to avoid spurious diffs in darcs

* the tab character should not appear in any source file except the Makefile
and the otl files.

* 4 space indents should be used.

* unless it can fit all on one line, a newline should come after let, do or
where so that the code is always indented in units of 4 spaces

* in general, I use under_scores for CAFs, global non-function names, and
tables. camelCaps for functions and CapCaps for data, type constructors, and
classes.