Naming Conventions

In order to avoid class name clashes between different libraries, some Eiffel compilers support class renaming in the Ace file or equivalent. But some don't. Therefore the name of the classes should systematically be prefixed with a two-letter library code followed by an underscore. For example the classes from the Gobo Eiffel Structure Library have been prefixed by DS (which stands for Data Structures), as in DS_CONTAINER, whereas classes from the Gobo Eiffel Lexical Library have been prefixed by LX, as in LX_SCANNER. Some libraries may use several prefixes, provided that they are not already used by other libraries. The list of already used prefixes per library will be available on-line.

Class names should usually be singular nouns, such as DS_STACK. If the noun is qualified, words should be separated by underscores, as in DS_LINKED_LIST. Class names in Eiffel are written in upper-case letters and it is considered bad style to use letter-case difference to concatenate words such as LinkedList for example. The name of deferred classes can also be adjective when they describe a property, such as DS_SORTABLE. It is suspicious to have verbs as class names since classes should describe objects rather that actions.

Classes containing only constants can have the suffix _CONSTANTS and those containing only facility routines can have the suffix _ROUTINES. Some classes are used as a means to share objects using once functions. These classes can have the word SHARED just after the prefix of the class. For example the class used to share a singleton object of type KL_ARGUMENTS is called KL_SHARED_ARGUMENTS. An alternative is to use IMPORTED instead of SHARED when the purpose of the class is not to give access to an object but rather to routines or constants without the inconvenience of polluting the feature name space with mixin classes. Have a look at KL_IMPORTED_STRING_ROUTINES as an example.

In Eiffel it is considered bad practice to use abbreviations in class and feature names. However this can be accepted when the abbreviation is commonly used in the domain of expertise such as LX_DFA for example, which stands for Deterministic Finite state Automaton and is used for compiling regular expressions.

Visual Eiffel allows to have several classes in the same file, but the other Eiffel compilers don't. So each file should contain only one class.

Likewise, SmartEiffel expects by default to have a one-to-one relation between the name of the class and the name of the enclosing file. Therefore the name of the file should be the name of the class followed by the extension .e, all in lower case. For example file ds_list.e contains class DS_LIST.

Library classes should be organized in clusters in $GOBO/ library/[library-name]. Likewise the source code of tools should be put in $GOBO/src/[tool-name].

Cluster names should be in lower-case and words should be separated by underscores. Abbreviations should be avoided unless well accepted and understood in the domain of expertise of the underlying library. Exceptions to this rule are spec for Eiffel compiler dependent clusters and impl which stands for "implementation". For the cluster spec, compiler-dependent classes should have the same name and put into the four following clusters:

Only one of these clusters will be included in the Ace file, loadpath file or ESD file of the application depending on the Eiffel compiler used. These clusters can be automatically generated with the tool gepp if the different implementations are put in a single file whose extension is .ge instead of the Eiffel extension .e. I usually find it easier for development and maintenance to have these .ge files.

For impl cluster, it can be used to provide several implementations of a common interface. For example:

Here again the names of the classes in the different subclusters of impl will be the same, and only one of these subclusters will be included in the Ace file or equivalent in order to provide a concrete implementation of the deferred classes in cluster interface.

Cluster impl can also be used with the bridge pattern. In that case the cluster structure will look like this:

  foo
  bar
  impl/interface/foo
  impl/interface/bar
  impl/gtk/foo
  impl/gtk/bar
  impl/motif/foo
  impl/motif/bar

The classes in gtk and motif implement the deferred classes in interface, and in the Ace file or equivalent the clusters with tk or with motif will be included depending on the fact that GTK+ or Motif has been chosen to build the graphical interface for example.

Feature names should be in lower-case and words should be separated by underscores. Abbreviations should be avoided unless well accepted and understood in the domain of expertise of the class. Names of constants can possibly have upper-case letters, but in that case please make sure that all calls to this constant use the same letter-case in order to be compilable by SmartEiffel without requiring the -no_case_sensitive command-line option.

Names of procedures should be verbs as they describe actions or commands. On the other hand names of functions or attributes should be nouns, possibly qualified, as they describe entities. The names of boolean queries should have an interrogative form as in is_empty, is_closed or has_error. They can also be simple adjectives such as closable, or past participles as in found.

Names of creation procedures usually start with make in Eiffel, for example make or make_from_string.

Names of factory functions can have the prefix `new_*', as in the following example:

_   new_foo (a_string: STRING): FOO is
_   _   _   -- Foo made up fo characters of `a_string'
_   _   _   -- (Create a new objet at each call.)
_   _   require
_   _   _   a_string_not_void: a_string /= Void
_   _   do
_   _   _   !! Result.make_from_string (a_string)
_   _   ensure
_   _   _   new_foo_not_void: Result /= Void
_   _   end

All feature clauses should be equipped with a comment, as in the following example:

feature -- Access
feature {NONE} -- Initialization
    

Here are some examples of feature category names, taken from the Gobo Eiffel Structure Library documentation:

  -- Initialization
       Creation procedures.
  -- Access
       Queries used to get elements or properties
       about the container.
  -- Measurement
       Queries concerning the number of elements
       and size of the container.
  -- Status report
       Queries used to determine general boolean
       properties of the container.
  -- Comparison
       Equality tests between containers.
  -- Duplication
       Features which produce copies of the container.
  -- Setting
       Procedures which change the general properties
       of the container.
  -- Cursor movement
       Procedures that change the cursor position.
  -- Element change
       Commands which add or change items in the
       container.
  -- Removal
       Commands which remove items from the container.
  -- Resizing
       Commands which change the size of the container.
  -- Implementation
       Secret features used for implementation purposes.