
QUALITY.TXT, (C) Yann GUIDON Tue Dec 12 20:08:29 MET 2000
(update : dec. 26th, 2001)

Quality policies and some helpful advices.

               ~~~~~~ testbenches ~~~~~~

Before i bore you with my old rants about why you should
document your code, let me start with a first design guideline :
"there should be one testbench for every design entity".
It really helps locate bugs as soon as possible and this
works whatever the langage. For example, if you have a file
called design_unit.c or design_unit.vhdl, you should start
programming a file called test_design_unit.c or test_design_unit.vhdl
that explores the parameter space as much as possible
(if the verification is performed higher in the design
hierarchy, the test vectors become too difficult to manage).

               ~~~~~~ documentation ~~~~~~

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
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. After all, this is a "public" work
and even if you own the Copyright on what you write, the purpose
is to be understood.

It is not possible to spend all your 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 is best written while programming.
for example :
       a = b + c; /* update the hit counter */

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 would 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 when it is first read. It is not a police investigation
story in which the evidences and the overall timeline can be
mixed, just for the suspense. A source code must tell you a
simple, linear story : carefuly selected comments with a good style
(i mean : not "only" a descriptive comment such as
    a = b + c; /* add b to c and put the result in a */
) 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.

One could object that commenting the files takes time.
Compared to the usually slow development rate, it is a very small
temporal impact, with a significant quality enhancement.
writing a single line takes 5 or 10 seconds and a file can contain
hundreds or up to thousands of lines. This is nothing compared to
the time wasted debugging or reverse-engineering undocumented code.


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.
This "habit" helps keep track of the modifications, either
in a CVS environment or not. The copyright and license notice
are also very important : not because they look pretty but
because of the legal threats in our fields.

- 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 single file, a directory, a package...

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,
it can increase or decrease because computer science is
not a linear matter...

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 or "distributions" 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.

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

I would like to also promote a very good practice (not only in
computer science but in any science or human industry) called
"peer review". The ideal case would be that a piece of code is
released if it has been positively tested and read by at least
3 different people. Unfortunately, the project has not gained
enough momentum to justify such "overhead" but this is also a
good way of learning from other's coding practices. Reading
source code is always instructive.


Update from Fri Jun 21 11:55:15 CEST 2002 :
the source tree contains illustrations in PostScript vector file
format. The source files are usually tgif, but must be provided
anyway (to ease the updates). A little drawing is often worth
a lot of text, so it's worth the effort. Some of the illustrations
can also be reused later in the manual, for example.

