Programming Style
Assertions
Routines should be properly equipped with pre- and postconditions and classes with invariants. This is useful as documentation in addition to the header comments to make sure that the routines and class instances are correctly used. Assertions should be enabled whenever possible during testing of examples.
All assertions should have a tag, as in the following example:
_ foo_not_void: foo /= Void
Note that in the example above the tag “foo_not_void” is preferred to “foo_exists” as it may cause confusion when exists is a feature of the class of foo. So using systematically “*_not_void” is a good way to avoid such possible confusion.
Indexing Clause
Each class should have an indexing clause at the top of the file which looks like that:
indexing _ description: _ _ "Short description of the class" _ date: "$Date$" _ revision: "$Revision$"
Put a short description of the class in the “description” field.
The fields “date” and “revision” are automatically expanded by CVS.
Header Comments
Every feature and feature clause should have a header comment such as:
feature -- Access _ title: STRING _ _ _ -- Title displayed in the title bar feature -- Element change _ set_title (a_title: like title) is _ _ _ -- Set `title' to `a_title'. _ _ require _ _ _ a_title_not_void: a_title /= Void _ _ do _ _ _ title := a_title _ _ ensure _ _ _ title_set: title = a_title _ _ end
(Borrow guidelines to write good header comments from OOSC2 section 26.4 page 886-888.)
Feature Clauses
Features should be grouped in one of the following feature clauses:
Initialization Access Measurement Comparison Status report Status setting Cursor movement Element change Removal Resizing Transformation Conversion Duplication Miscellaneous Basic operations Drawing Events Mouse management Keyboard management Joystick management $user_defined$ Obsolete Inapplicable ImplementationFeature clauses should be in the same order presented here. Only feature clauses which have features are present in a class.
If no feature clause fits the feature, a new clause can be added in the $user_defined$ section.
Free Comments
They should give useful information and not just paraphrase the software text. They should appear on the line before the instruction(s) to be explained and should have one more indentation level to the right than the instruction(s).
Exceptions
Exceptions should only be raised when an unexpected behavior occurs. Reading an integer from the standard input when the user actually typed “hello”, or trying to open a file in read mode when the file does not exist (it could just have been deleted) are not considered as unexpected behaviors in my point of view.
Also raising exceptions in the creation routine should be avoided since it is not clear (unless I'm proven otherwise) that ETL describes precisely what should happen in that particular case. It is preferred to properly create the objects and then call the routines which may raise the exception.
Routines which may raise exceptions should make it clear in their header comment. (There is no need to report the fact that a No_more_memory exception can be raised in each routine creating objects though ;-))