
QUALITY.TXT, (C) Yann GUIDON Tue Dec 12 20:08:29 MET 2000


Quality policies and some helpful advices


I must recognize that i'm not the best coder of the world.
My memory is limited and I sometimes face difficult compromises
that affect the code i write, whatever the langage.

We all know that a good documentation and easy to use SW are
more sometimes more important than the speed or usefulness
improvements. For example, you just discovered this text and
you decided to read it. You have opened it in a text editor
of your choice, assuming (from the .TXT file extension) that
it is in ASCII format. You now enjoy its insightful contents
and it all lasted only a few seconds :-)

The same goes for source code.


The goal of this document is not to "rule" but to "guide"
coders, whatever their project. When a package must be released,
it is often very long to check the consistency and status
of every file. Even though it's not considered as a "noble" task,
each one should consider spending a large amount of time
writing comments and READMEs.

It is not possible either to spend all you time writing documents,
but please consider the total amount of time that will be spent
by people trying to understand your code. If you code all the time,
you don't document, and if you write comments all the time, there
is no code written in the end.

That is why the document must be written while programming.
It doesn't take much time at all because it is an integral part
of the coding activity and it follows closely your ideas of the
moment. For one ASCII character of code, there should be in
average one character that describes what is being done. This
average concerns the whole file. This kind of documentation is very
helpful, not only for the newcomer, but for the coder himself,
because it helps him debug the code. When the code is ready and
ready for distribution, an external file (ie HTML) can be written,
describing the overal architecture of the code and the basic
principles.

I consider a program source file as a story that should be
understood with the first reading. A source code must tell you a
story : good comments with a good style (not "only" a descriptive
comment) can explain what is really going on. Old good
spaghetti style is not good. Not because it is spaghetti,
not because it makes use of direct jumps or labels (we always
need some from time to time) but because the structure doesn't
appear during a linear reading.


Now, here are some practical, everyday advices :

- When creating or updating a file, always put the copyright, the
author's (you) name, and the date. I usually type "date"
on a Un*x console and then cutn'paste it in emacs.

- indicate as much hints as possible, even though it ends up
with pages of comments. they'll be sorted later if they're
useful. Removing comments might lead to some misunderstanding
with others.

- here are some standard hints, after the date and name :
* type of modification : several lines are often necessary
(unless you only mistyped a character...)
* name of the file. It might be lost when sent in an email
or when printed, depending on the software (do not think that
because your SW does it for you, the others will have it too).
* compilation command, or indication of the makefile.
This shows what flags and compiler are needed.
* if it is included in another source, name the file.
* Portability across platforms : indicate what tool is used
(ie a certain flavour of)
or if there are incompatible features (ie: a particular
data alignment/ordering/organisation, CPU-dependent structures...)
* Link to documentation : in the directory or in the package,
or on the web, etc...
* whether is is tested, how and in what circumstances (platforms,
dataset, coverage...)
* Status of the file : something like the following notes
 -> just created, 
 -> not yet working
 -> just working
 -> enhancements
 -> satisfying
 -> a bug was discovered somewhere...
 -> foolproofed
 -> don't touch
 -> locally released
 -> ready for public release

The hints apply for a sing file, a directory, a package...
Note that the 

These hints are highly subjective and are influenced by 
everyone's standards. This evaluation can be summarized in a single
number, from 0 to 10.
* 0 corresponds to a rather inexistent or empty package
* 1 : the first functions are written
* 2 : some stuffs are starting to work together
* 3 : addition of some test vectors and testbenches
* 4 : under debug
* 5 : enhanced
* 6 : all features are available
* 7 : correctly working
* 8 : fully documented
* 9 : exhaustively tested across many platforms
* 10 means that it can't be enhanced anymore.
Of course this is only indicative about the general status.
The mark can vary a lot during the life of the project.


The goal of thes hints and subjective evaluations is to help
maintain and bundle the packages. A directory containing
low-evaluated files will not be included in a package.

Ideally, a package should only contain "10" files but in
practice and in a closed-room development environment,
some factors are not revelant. A F-CPU package would average
8 for practical reasons (time, platforms, prototyping/evaluation
only etc).


Today (dec. 2000), all the files of the F-CPU project don't
comply with this policy. Before the distribution grows out of
control, it becomes necessary to closely examine, document
and test all the source code. Then, only "satisfying" files
or directories would be included in a certain package (as several
F-CPU packages are possible).

                       -----------------

I hope that this text has helped you understand the importance
of individual quality evaluation. Next time you finish a software,
don't think that it is ok : higher quality means less time
spent during debug sessions and packaging. It also means more
attention on the code writing : correctly indenting a source file
is not enough.

Please spend more time explaining what you do (on the file).
Remember that few good working code files are better than a whole
bunch of unorganized, unsorted, undocumented files that don't
work. The first has more value because it can be easily compiled,
executed, modified and redistributed.
