Chapter 1. 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. These assertions can also be enabled when running the test suite in $GOBO/test/[library-name] in order to check the correctness of the library classes.

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"

_   library:    "Gobo Eiffel Lexical Library"
_   author:     "Eric Bezault <ericb@gobosoft.com>"
_   copyright:  "Copyright (c) 2000, Eric Bezault and others"
_   license:    "Eiffel Forum License v2 (see forum.txt)"
_   date:       "$Date: 2004/04/30 23:38:45 $"
_   revision:   "$Revision: 1.1 $"

Put a short description of the class in the description field. Replace "Lexical" in the library field by the name of your library. Replace "Eric Bezault" by your name in the author and copyright fields and put your e-mail address in the author 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 -- Setting

_   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.)

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

Semicolons

Semicolons are optional in Eiffel. For consistency reason, they should not be used in the Gobo Eiffel classes. The only places where they are used are:

to separate formal arguments of routines:

       f (a_foo: FOO; a_bar: BAR) is

to separate several instructions on the same line, although this programming style is not recommended:
```
       print ("Hello "); print (you.name)
          
```

to remove parsing ambiguity:

            foo.bar;
            (baz).do_something

SmartEiffel emits a warning when semicolons are missing in the Export subclause of the Feature_adaptation clause. Semicolons can be added here in order to keep SmartEiffel quiet.

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 unexpected behaviors by Eiffel programmers.

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 ;-))