Doc/technotes/coding_guidelines.txt

Title: Coding Guidelines for Thuban
Author: Bernhard Herzog <[email protected]>
Last-Modified: $Date$
Version: $Revision$


Introduction

    To keep the Thuban code maintainable all code should adhere to the
    guidelines outlined below.  The guidelines currently cover stylistic
    issues (e.g. rules for source code formatting) as well as Python
    programming hints and rules for using CVS and making patches.


Source Formatting

    Python and, where applicable, C/C++ source code should be formatted
    according to these rules:

    - All lines should be at most 79 characters long

    - Put spaces around binary operators and after commas, colons and
      semicolons.  Do not put spaces before commas, colons and
      semicolons and don't put them after opening or before closing
      parentheses, brackets and braces.

    - Use only spaces for indentation.  Each indentation level is four
      spaces.

    - Every class, function and method should have a doc string.  The
      doc string should start with a brief one-line description of the
      class or method.  If more explanations are needed add an empty
      line and one or more paragraphs.

    - Put imports at the top of a module.  Put the more fundamental
      import statements first, and the more Thuban specific later.
      E.g. imports from the standard library come first, then import
      statements for third-party modules, then Thuban imports.  Imports
      from the same Thuban sub-package come last.


Python Programming

    - Thuban must remain compatible with Python 2.2.

    - Do not use "from module import *"

      This form of the import statement leads to code that is hard to
      maintain for several reasons:

      - When the module's contents change, the names bound in the code
        that executes the import statement change as well and might
        accidentally override python builtins or names already bound in
        the module

      - It's hard to find out which of the objects in the imported
        module are actually used by the importing code.  It's especially
        hard to find out whether the import is still needed if the code
        has changed.

    - Do not check the type of parameters

      Functions and methods should be coded to interfaces, not types, so
      checking whether an object passed as a parameter to a function is
      of a certain type or an instance of a particular class is almost
      never a good idea.

    - Use "obj is None" when testing for None not just "obj".  The
      object in question might be false without being None.


Test Suite

    Thuban has a fairly comprehensive test suite in the test/
    subdirectory.  The test suite is only useful if it is kept up to
    date and if it is run often.  Therefore:

    - Before a checkin, run the *entire testsuite*.  Yes, all of it.
      Even if you think your change won't break anything.

    - New functionality and bug fixes should have corresponding tests in
      the test suite.

    - The tests should use only public interfaces.

    - Write the tests before writing the code.

    - It should be possible to run the test suite without an X server
      being present.


CVS

    - One can't say this often enough: Before a checkin, run the *entire
      testsuite*.  Yes, all of it.  Even if you think your change won't
      break anything.

    - All commits should be described in the ChangeLog file.  The esiest
      way to do that is to write the ChangeLog entry first and use that
      as the commit message.

      For emacs users: Use emacs' CVS support (e.g. `C-x v =' in a
      modified file's buffer) to get a diff and then use `C-x 4 a' at
      appropriate places in the diff to start the ChangeLog entry.

    - Try to make small self contained commits.  In particular, if
      during the work on a more complex change you discover a bug,
      commit the the fix to that bug separately with a separate
      ChangeLog entry.


Patches

    - When you produce patches please try to produce them as patches
      against a current CVS version.  A patch against code from a
      tarball is often OK too but can make it more difficult to test a
      patch if e.g. the files in CVs have changed considerably.

    - Please make context diffs, i.e. use the -c option of diff or cvs
      diff.  The default output of diff is not suitable for a patch.

    - Treat a patch like CVS commit.  That's what it will end up as if
      it is accepted, so if you want to increase the chances that it
      will be applied, please try to make the work easier for us, and
      make sure the test suite still works, add new tests if your patch
      adds functionality or fixes a bug and write a ChangeLog entry.
1	bh	2093	Title: Coding Guidelines for Thuban
2			Author: Bernhard Herzog <[email protected]>
3			Last-Modified: $Date$
4			Version: $Revision$
5
6
7			Introduction
8
9			To keep the Thuban code maintainable all code should adhere to the
10			guidelines outlined below. The guidelines currently cover stylistic
11			issues (e.g. rules for source code formatting) as well as Python
12			programming hints and rules for using CVS and making patches.
13
14
15			Source Formatting
16
17			Python and, where applicable, C/C++ source code should be formatted
18			according to these rules:
19
20			- All lines should be at most 79 characters long
21
22			- Put spaces around binary operators and after commas, colons and
23			semicolons. Do not put spaces before commas, colons and
24			semicolons and don't put them after opening or before closing
25			parentheses, brackets and braces.
26
27			- Use only spaces for indentation. Each indentation level is four
28			spaces.
29
30			- Every class, function and method should have a doc string. The
31			doc string should start with a brief one-line description of the
32			class or method. If more explanations are needed add an empty
33			line and one or more paragraphs.
34
35			- Put imports at the top of a module. Put the more fundamental
36			import statements first, and the more Thuban specific later.
37			E.g. imports from the standard library come first, then import
38			statements for third-party modules, then Thuban imports. Imports
39			from the same Thuban sub-package come last.
40
41
42			Python Programming
43
44			- Thuban must remain compatible with Python 2.2.
45
46			- Do not use "from module import *"
47
48			This form of the import statement leads to code that is hard to
49			maintain for several reasons:
50
51			- When the module's contents change, the names bound in the code
52			that executes the import statement change as well and might
53			accidentally override python builtins or names already bound in
54			the module
55
56			- It's hard to find out which of the objects in the imported
57			module are actually used by the importing code. It's especially
58			hard to find out whether the import is still needed if the code
59			has changed.
60
61			- Do not check the type of parameters
62
63			Functions and methods should be coded to interfaces, not types, so
64			checking whether an object passed as a parameter to a function is
65			of a certain type or an instance of a particular class is almost
66			never a good idea.
67
68			- Use "obj is None" when testing for None not just "obj". The
69			object in question might be false without being None.
70
71
72			Test Suite
73
74			Thuban has a fairly comprehensive test suite in the test/
75			subdirectory. The test suite is only useful if it is kept up to
76			date and if it is run often. Therefore:
77
78			- Before a checkin, run the entire testsuite. Yes, all of it.
79			Even if you think your change won't break anything.
80
81			- New functionality and bug fixes should have corresponding tests in
82			the test suite.
83
84			- The tests should use only public interfaces.
85
86			- Write the tests before writing the code.
87
88			- It should be possible to run the test suite without an X server
89			being present.
90
91
92			CVS
93
94			- One can't say this often enough: Before a checkin, run the *entire
95			testsuite*. Yes, all of it. Even if you think your change won't
96			break anything.
97
98			- All commits should be described in the ChangeLog file. The esiest
99			way to do that is to write the ChangeLog entry first and use that
100			as the commit message.
101
102			For emacs users: Use emacs' CVS support (e.g. `C-x v =' in a
103			modified file's buffer) to get a diff and then use `C-x 4 a' at
104			appropriate places in the diff to start the ChangeLog entry.
105
106			- Try to make small self contained commits. In particular, if
107			during the work on a more complex change you discover a bug,
108			commit the the fix to that bug separately with a separate
109			ChangeLog entry.
110
111
112
113			Patches
114
115			- When you produce patches please try to produce them as patches
116			against a current CVS version. A patch against code from a
117			tarball is often OK too but can make it more difficult to test a
118			patch if e.g. the files in CVs have changed considerably.
119
120			- Please make context diffs, i.e. use the -c option of diff or cvs
121			diff. The default output of diff is not suitable for a patch.
122
123			- Treat a patch like CVS commit. That's what it will end up as if
124			it is accepted, so if you want to increase the chances that it
125			will be applied, please try to make the work easier for us, and
126			make sure the test suite still works, add new tests if your patch
127			adds functionality or fixes a bug and write a ChangeLog entry.
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision