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 SVN 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.

    - Method names start with lower case letter.

      The main reason is that we should, in the long term, adopt the more
      common naming styles used in python code.  For Thuban this basically
      means not to start method names with upper case letters. For Thuban this
      would be a substantial change and even though it would be easy to retain
      the old method names for a while for backwards compatibility it's not
      something that should be done soon.  However, new classes should
      follow this rule.

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.


SVN

    - 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 easiest
      way to do that is to write the ChangeLog entry first and use that
      as the commit message. Maybe your editor has support to help with this.

    - 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 SVN 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 SVN have changed considerably.

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

    - Treat a patch like SVN commit.  That is 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	bernhard	2678	programming hints and rules for using SVN and making patches.
13	bh	2093
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	jan	2332	- Method names start with lower case letter.
72	bh	2093
73	jan	2332	The main reason is that we should, in the long term, adopt the more
74			common naming styles used in python code. For Thuban this basically
75			means not to start method names with upper case letters. For Thuban this
76			would be a substantial change and even though it would be easy to retain
77			the old method names for a while for backwards compatibility it's not
78			something that should be done soon. However, new classes should
79			follow this rule.
80
81	bh	2093	Test Suite
82
83			Thuban has a fairly comprehensive test suite in the test/
84			subdirectory. The test suite is only useful if it is kept up to
85			date and if it is run often. Therefore:
86
87			- Before a checkin, run the entire testsuite. Yes, all of it.
88			Even if you think your change won't break anything.
89
90			- New functionality and bug fixes should have corresponding tests in
91			the test suite.
92
93			- The tests should use only public interfaces.
94
95			- Write the tests before writing the code.
96
97			- It should be possible to run the test suite without an X server
98			being present.
99
100
101	bernhard	2678	SVN
102	bh	2093
103			- One can't say this often enough: Before a checkin, run the *entire
104			testsuite*. Yes, all of it. Even if you think your change won't
105			break anything.
106
107	bernhard	2443	- All commits should be described in the ChangeLog file. The easiest
108	bh	2093	way to do that is to write the ChangeLog entry first and use that
109	bernhard	2678	as the commit message. Maybe your editor has support to help with this.
110	bh	2093
111			- Try to make small self contained commits. In particular, if
112			during the work on a more complex change you discover a bug,
113			commit the the fix to that bug separately with a separate
114			ChangeLog entry.
115
116			Patches
117
118			- When you produce patches please try to produce them as patches
119	bernhard	2678	against a current SVN version. A patch against code from a
120	bh	2093	tarball is often OK too but can make it more difficult to test a
121	bernhard	2678	patch if e.g. the files in SVN have changed considerably.
122	bh	2093
123	bernhard	2678	- Please make context diffs, i.e. use the -c or -u option of diff or svn
124	bh	2093	diff. The default output of diff is not suitable for a patch.
125
126	bernhard	2678	- Treat a patch like SVN commit. That is what it will end up as if
127	bh	2093	it is accepted, so if you want to increase the chances that it
128			will be applied, please try to make the work easier for us, and
129			make sure the test suite still works, add new tests if your patch
130			adds functionality or fixes a bug and write a ChangeLog entry.
Name	Value
svn:eol-style	native
svn:keywords	Author Date Id Revision