A SHORT GUIDE TO GOOD CODING
		     ============================

This text summarises some good habits when coding, whatever the
programming language you use. Please try to follow them while coding
for your project.

Documentation
-------------

Your code should be self-documented as much as possible. This means
more than adding comments; it means also making your variable and
function names meaningful. Thinking well your names is one of the best
way to make a program readable.  Comments should also be there, but
not just to repeat each line of code--that, everyone
understand. Rather, they should tell *why* you're doing something or
summarise the behaviour of the most important functions, for example.


Variables
---------

No global variables when they are not needed. Always declare a
variable with the smallest necessary scope.


Magic numbers
-------------

Never write:

   int matrix[400];

What is this 400?! Is it the maximum size of basic blocks?!  Then one
should write:

   #define MAX_SIZE_BB 400
   int matrix[MAX_SIZE_BB];

Clearly, no 400 should appear anywhere in the code, now. No constants
should ever appear in your code, apart possibly from 1 and 0.


Memory allocation
-----------------

It's good to get rid of magic numbers, but in the previous case:

   int matrix[MAX_SIZE_BB];

is still very bad!

Be assured that you will always find a basic block larger than your
MAX_SIZE_BB, so your program will core dump in all those cases
(hopefully!--otherwise it will produce wrong results without you
knowing it).  Hence, it is hugely important to use dynamic memory
allocation (malloc) whenever the size of your structure is not known
at compile time.

Once allocated, memory should be freed as soon as it is not needed
anymore. Memory leaks are bad for performance and a common source of
errors. Use memory analysis tools such as Purify to make sure your
code is properly releasing all memory.


Functions
---------

You should organise your code in functions. No function should be
longer than, say, 200 lines of code, but in general it should be much
shorter.  Even functions of 4 lines can help a lot the readablility of
your code.  Organising your code in functions is much easier to
understand and to debug.

Also, it is said that the upper limit for the number of function
parameters is about 7, or the code will be much less readable.


Code layout
-----------

A consistent and easy to visualise code layout style should be
used. Use indentation. Write only one statement per line. Use good
editors, such as xemacs, supporting automatic indentation and possibly
colours: They'll help you spot errors even before compiling.  Use only
spaces for indenting (for example 3 spaces for each level) and not
TABs.  All decent editors can be configured to use spaces instead of
TABs.  Each line of code should not exceed the length of 80
characters, unless it improves readability.


Language
--------

Everything in your code (e.g. variable and function names or comments)
should be in English.


Versioning
----------

Use versioning tools such as RCS or CVS. They are available on all
platforms and their use costs almost nothing while the advantages of
tracking changes and having a clear history are huge. Never rename or
copy files to names such as myprogram-old.c or myprogram-041023.c. Use
versioning tools instead and don't write even only a line of code
before your development environment is properly set up.


Makefiles
---------

Use makefiles not only as an automation help, but also as a way to
document how things should be compiled or used. Include in the
makefile commands to run testcases.


VHDL specifics
--------------

All active low signals should be very clearly identifiable as such in
a consistent way, for instance by a prefix such as "n_" or a suffix
such as "_bar". All signals and variables should be very clearly
identifiable as such is a consistent way, for instance by a prefix
such as "s_" for signals, and "v_" for variables. All flip-flop and
latches should be very clearly identifiable as such in a consistent
way, for instance by a suffix "_reg" for flip-flops and "_latch" for
latches.  Each file should only contain one entity with its behavior,
and should be named identical to the name of the entity suffixed with
".vhdl".

-- $Id: coding.txt,v 1.4 2007/01/11 08:37:08 ienne Exp $