README.sources

                                                            -*- Text -*-

		       Coding Guidelines for QM


Please observe these guidelines when writing, modifying, and checking
in code and documentation for the QM project.


  - Create GNU-style ChangeLog entries for all program changes before
    checking anything into CVS.  A description of GNU ChangeLogs is
    available at <http://www.gnu.org/prep/standards_38.html#SEC38>.

    In most GNU/Linux distributions, the description is also installed
    in Info format.  To access them, type

      info "(Standards)Change Logs"

    Only minimal ChangeLog entries are required for documentation
    changes, for instance

        * documentation.txt: Add "Introduction" section.  Fix typos.

    However, all changes to Makefiles and other mechanisms used for
    machine processing of documentation, and changes to style sheets
    and related meta-information, should be accompanied by complete
    ChangeLog entries.


  - When creating a new source file, use the appropriate template from
    the templates subdirectory.  The template contains the project's
    copyright banner and similar formatting.

    All source files, documentation files, Makefiles, etc. must carry
    the standard copyright banner and a summary of the file's
    contents.


  - Wrap all text to 72 columns.


Instructions for writing documention:

  - Documentation should be written in DocBook XML.


Instructions for writing code:

QM software should be written to work with Python 2.1 or higher.
Python source code should adhere to Guido van Rossum's "Python Style
Guide", available at

    http://www.python.org/doc/essays/styleguide.html

subject to the following modifications and clarifications:

  - Source text should ideally be wrapped at 72 columns.
    Occasionally, source code may extend to column 78, if this
    produces substantially clearer formatting.

  - Leave two blank lines between all functions.  Leave three blank
    lines after class definitions. 

  - Use double quotes for string literals, unless there is a reason to
    use single quotes (such as that the literal contains double quotes).

  - All unary operators should be followed by a single space.  All
    binary operators should have a single space on each side.

    Examples:
      c = (a + b) * (a - b)
      substring = x[ : i - 4]

    Exceptions:
      unary minus:              c = -b
      comma:                    (a, b, c)    (a, b, c, )
      colon in statements:      if x == 4:

  - When breaking lines at operators, place the operator on the second
    line.

    Example:
      if some_condition () \
         and j < i + 2:
	  c = first_function (i) \
	      + second_function (j)

  - All comments and doc strings should be written in full sentences.
    Capitalize the first word of the sentence, unless it is a name
    from source code (and try to avoid this case).  End each sentence
    with punctuation, and separate sentences with two spaes.

  - Avoid placing comments on the same line as code.  A comment in the
    body of a function should be placed on the line(s) above the code
    it comments.

  - Do not use special CVS substitution keywords ("Id:, "Author:",
    etc.) in source code.

  - Always use the following naming conventions:

      Item               Style
      ----------------------------------------
      modules            underscore_delimited
      classes            CamelCaps
      global names       underscore_delimited
      class methods      CamelCaps
      class attributes	 underscore_delimited
      local variables    underscore_delimited

For class attributes and methods, use a name that starts with a single
underscore for members that would be protected in C++, i.e. meant to be
accessible by the class itself and its subclasses only.  Use a name that
starts with two underscores for members that would be private in C++,
i.e. meant to be accessible only by the class itself.  In global scope,
use names that begin with a single underscore for functions and
variables that would be static in C or C++, i.e. meant to be used within
the package only.

Every program element (module, class, function, etc.) should be
provided with a doc string.  Doc strings should be written in
structured text, using full sentences.  Begin and end all doc strings
with three double quotes (""").

The first line of each doc string should be a short summary sentence
for the item.  If necessary, a detailed description should follow,
separated by a blank line.  All source code names (such as variable
and parameter names) mentioned in doc strings should be surrounded by
single quotes.

All function parameters should be documented (except for self, for
class methods).  Return values, preconditions, postconditions, and
potentially raised exeptions should also be mentioned explicitly.
These may be documented in the text description of the function, or as
a definition-style list (write the name of the parameter, two dashes
(--), and then a description.  For example,

    def read_file(file, filter=None):
	"""Read data from a file, filtering as necessary.

	preconditions -- 'file' is rewound to the beginning.

	'file' -- A file object to read from.

	'filter' -- A 'FooFilter' instance, or 'None' for no filtering.

	raises -- 'IOException' if 'file' cannot be read.

	postconditions -- 'file' is closed.

	returns -- The filtered data."""

Doc strings should be used for interface documentation, i.e. the
information that another programmer needs to know to use the element
correctly.  Implementation, i.e. how a function actually does its job,
should be commented using ordinary comments.

Environment variable names used in QM (other than those with standard
meanings like "PATH") should be composed entirely of upper-case
letters and underscores.  Variables that apply to all QM tools should
begin with "QM_".  Variables that apply to a particular tool should
begin with "QM<tool>_".  Examples:

  QM_PYTHON
  QMTEST_CLASS_PATH
  QMTRACK_DB_PATH

All source code checked into the QM source repository should comply
with these guidelines.