What is considered good programming style in the Tunes project.
STYLE,v 1.1.1.1 1998/11/26 04:10:47 tunes Exp


   This document tries to define some rules for project members to
follow while coding.
   Members please do not hesitate to argument against it if you disagree.
You need not follow these recommendations in parts you maintain, as long
as you are ready to maintain it.
   The whole point about such a programming style,
is that we should minimize a function that expressed human maintainability.
That is, redundancies should be encouraged where they help understand,
and discouraged when they are just noise and hassle.
   Note that a good editor should allow the programmer to use typing
shortcuts, so that what reads redundantly needn't be written in a
redundant manner.



******************************************
*** Rule 1: Factor as much as possible ***
******************************************

first order factoring
---------------------
   Every common sub-expression that appears three times or more
must be factored into applying a defined function,
unless the expression is smaller than the function's name
*and* the common part is all on the same part of the syntax.
   For instance
	(foo x bar) (foo y bar) (foo z bar)
where size of foo, x , y, z, bar vary,
should generally be factored by the definition
	(define foo-x-bar (x) (foo x bar))
   while
	(foo bar x) (foo bar y) (foo bar z)
should not be factored if foo and bar are small enough.



second order factoring
----------------------

   Similarly, long lists of similar constructors are not welcome:

	(define-instruction A1 B1 C1 D1)
	(define-instruction A2 B2 C2 D2)
	...
	(define-instruction An Bn Cn Dn)

should be factored into
	(map-macro define-instruction
		((A1 B1 C1 D1)
		 (A2 B2 C2 D2)
		  ...
		 (An Bn Cn Dn)))
using the appropriate map-macro macro.




factoring multiplexing
----------------------

   If there is a union type made of several kinds of objects,
objects should not be prefixed by constructors when not necessary,
thanks to constructor words that would demultiplex the objects into,
and deconstructor words that would multiplex them again.
   An example is how assembler instructions, directives, and macros
are multiplexed.



*********************************************
*** Rule 2: avoid any manual optimization ***
*********************************************

   Optimizations should be done by the compiler.
If the compiler ain't good enough to optimize properly in reasonable time,
it should be given hints through annotations.
If the compiler doesn't accept annotations and programmable tactics,
it ain't worth anything; get one that can, or help us build one.


No manual inlining
------------------

   If the semantics of some code is not obvious,
or if it wouldn't be once some subexpression is factored out,
most likely, there was manual inlining done somewhere.
Keep it out ! Beta-expansion is a work for the inferior beings like machines,
not for humans.
   If your programming environment requires you to do manual inlining
to achieve any performance, then change your environment.
If you are compelled to use such a lame environment,
and cannot convince your stubborn clients
that the environment should be changed,
then write a meta-programming environment
that will produce code for the target environment you are bound to.



*************************************
*** Rule 3: choose readable names ***
*************************************

   What a readable name is is a discutable question,
and no opinion seems obviously better than another.
Which is why this section contains some arbitrary conventions.
   If you disagree, can discuss those style issues
with the code maintainer for the considered subproject
(unless a maintainer for a higher subproject is setting rules).
Of course, don't expect to win unless you have strong arguments,
or you are the maintainer yourself...
   Exact choice of name depends on what the language's syntax allows,
and what the subproject is trying to achieve.


Use the whole available character set
-------------------------------------

   The character set is poor enough,
there's no need to make it poorer even.
Using the whole of it increases the contrast between symbols,
and makes the whole sources more readable.
   In particular, both Uppercase and lowercase letters should be used,
whether the language written makes a difference or not,
and even if it doesn't, should be used as if it did.
Any available symbols like _@-:/+$#&!? should be used as well.


Have symbol describe type
-------------------------

   If the language written does not offer implicit type checking,
you should follow explicit type-checking by including (part of)
the symbolized object's type in the name:
   For instance, Scheme predicate names should end with a question mark "?".


Choose names that describe functions
------------------------------------

   Even though it may mean long names, have names describe what a
function do.
	"Increment-Counter-i-then-Go-to-sleep"
is a better name than "function2", or "inc-sleep".

   If needed, have names describe the calling convention by referring to
argument place:
	(define (foo-<2>-<1> x y) (foo y x))
might be a good choice.


Use scoping, modularity, and local renaming, to make names shorter
------------------------------------------------------------------

   Despite the above requirements,
you can still have short names,
by using scoping/modularity techniques;
the only requirement is that a name should avoid anything
that's source of a clash.
   When the system is bootstrapped, it will be possible
to dynamically and locally choose between short names and long names
(i.e. Joe will see long names whereas Francois-Rene will see short names).
with the system ensuring consistency.
   Meanwhile, consistency must be ensured manually,
hence we must care a lot.


Balance name length
-------------------

   Avoid short names in a global (or largely used) scope,
but for objects used everywhere.
   Actually, name length should be such that the extended language
be as near as possible of what linguists call an "optimal" language,
with least possible quadratic variation of the information density
per syllabus.
