[update conventions document
John Meacham <john@repetae.net>**20051018014310] hunk ./docs/conventions.txt 1
+= Various conventions for Jhc coding =
hunk ./docs/conventions.txt 3
-internal naming:
+== internal naming ==
hunk ./docs/conventions.txt 5
-for a variety of reasons, the compiler needs to generate haskell names
+for a variety of reasons, the compiler needs to generate Haskell names
hunk ./docs/conventions.txt 7
-psuedomodule that ends in '@' so it cannot conflict with any real module.
+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.
hunk ./docs/conventions.txt 12
-Instance@ - contains the implementation of all instance methods and the
-   defaults for a class
+* Instance@ - contains the implementation of all instance methods and the
+   defaults for classes.
hunk ./docs/conventions.txt 15
-LL@ - these are generated by lambda lifting functions to the top level
+* LL@ - these are generated by lambda lifting functions to the top level.
hunk ./docs/conventions.txt 17
-W@ - this is the worker of a worker/wrapper split
+* W@ - this is the worker of a worker/wrapper split.
hunk ./docs/conventions.txt 20
-when a name is generated from an existing one, the convention is to append
-'$n' for some number that makes the name unique.
+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.
hunk ./docs/conventions.txt 23
+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, Jhc
+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. haddock style comments
+should be included liberally.
+
+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.
hunk ./docs/conventions.txt 61
-code style:
+== code style ==
hunk ./docs/conventions.txt 63
-lines should have no trailing whitespace to avoid spurious diffs in darcs
+* lines should have no trailing whitespace to avoid spurious diffs in darcs
hunk ./docs/conventions.txt 65
-the tab character should not appear in any source file except the Makefile
+* the tab character should not appear in any source file except the Makefile
hunk ./docs/conventions.txt 68
-4 space indents should be used.
+* 4 space indents should be used.
hunk ./docs/conventions.txt 70
-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
+* 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
hunk ./docs/conventions.txt 73
-in general, I use under_scores for CAFs, global names or tables and camelCaps
-for functions and CapCaps for data and type constructors.
+* in general, I use under_scores for CAFs, global names, and tables. camelCaps
+for functions and CapCaps for data, type constructors, and classes.