2001-2005
Eric Bezault
Eric
Bezault
ericb@gobosoft.com 8 March 2005

# Naming Conventions

All names appearing in the software, comments, directory names, documentations, etc. should be written in American English.

## Class Names

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 `D`ata `S`tructures), 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 than 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 `D`eterministic `F`inite state `A`utomaton and is used for compiling regular expressions.

## Filenames

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

## Cluster Names

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 three following clusters:

> `spec/ise` Implementation for ISE Eiffel
> `spec/se` Implementation for SmartEiffel
> `spec/ve` Implementation for Visual Eiffel

Only one of these clusters will be included in the Ace file, loadpath file or ESD/Xace 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:

> `interface`
> `impl/c`
> `impl/dotnet`
> `impl/eiffel`
> `impl/jvm`
> `impl/posix`

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 `gtk` 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

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 of characters of a_string
    _   _   _   (Create a new objet at each call.)
    _   _   require
    _   _   _   a_string_not_void: a_string /= Void
    _   _   do
    _   _   _   create
    				Result
    				make_from_string
    				a_string

    _   _   ensure
    _   _   _   new_foo_not_void: Result /= Void
    _   _   end

## Feature Category names

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.