Fenestra User's Guide (appendix A) -- contents | previous | next
This appendix documents the specific Eiffel conventions which are used throughout this library. Overall, most of the standard style guidelines described in [meyer92] are respected.
The library uses consistently the following indexing clauses.
The cluster keyword is used to indicate which part of the library the current class belongs to. The first keyword usually describes the library itself, while the following keywords gives finer grain information about either a specific cluster inside the library, or similar classification information.
As expected, this entry includes a short textual description of the class.
The interface entry documents the way the class is to be used. The following keywords may be used:
For classes which are designed to be inherited by clients during normal use of the library, the public interface is the one exported to all clients (ANY) and, for redefinition purposes, the features exported to PUBLIC_NONE, an empty classification class.
This does not mean that the public interface will never be changed, but that all changes will be carefully thought out and compatibility with older code will be taken into account, while there will be no commitment to keep the internal features stable.
So, although Eiffel does prohibit neither redefinition nor invocations of any method when inheriting, it is recommended to use only the documented interface for normal use of inheritance as a library client.
Several assertions labels are used consistently to document the behaviour of the library features. The label may have a corresponding assertion, though it may have a simple comment when an assertion is not practical.
It is used in the postcondition of procedures which keep a reference (or equivalent) to an object passed as a parameter. This means that a subsequent change to an object, whose reference was passed as a parameter, can have an influence onto the object to which it was passed. The default case when this label is not present, is that the called feature does not to keep a reference to its parameters, who can be modified without further consequences after the feature call returns.
This label does not apply to purely expandedThe term purely expanded objects is used here to describe expanded objects which do not contain reference attributes to other objects, because otherwise the problem would be similar to the reference case. INTEGER, REAL, DOUBLE are examples of purely expanded objects. objects passed as parameters, because passing such an object is like passing a copy of the object (passing parameters by value in traditional programming languages).
This one is the counterpart to the preceding one; it is used in the postcondition of functions to document when the function's Result is a reference to an object which can be modified without consequences for the provider. It also means that every time the function is called, a new - distinct - copy will be delivered to the client. The default situation when there is no such label is that the function is either an attribute or returns a reference to an internal attribute of the object. The label doesn't apply to purely expanded function results.
This is similar to the preceding label, but indicates that while a new object is delivered to the client for each call, this object is still related to the provider. Therefore, altering this object may, in some cases, have side-effects on the provider.
This postcondition is used in a feature which is redefined but is not intended to be called by clients. It is equivalent to exporting the feature to NONE without the system level validity consequences, with the added benefit of making the feature being also unavailable to internal clients.
The documentation is generally written in British English except for well established computer terms such as computer program. The feature and class names follow a more conservative approach in using generally the common American English terms used for computer concepts throughout most computer software user interfaces and publications -- the British English term could appear odd to many users. The Eiffel feature synonym capability is used when having both is not a problem and it seemed useful. There is no systematic policy regarding the use of synonyms, which are not used where there can be no significant problem, such as -ise versus -ize.
Comments are considered to be part of documentation -- their spelling has no consequences on the code itself -- and are in consequence following the same British English policy as this manual. It is thus possible to encounter such oddities as a feature named synchronize being documented as a method to synchronise something.
One of the main concern during the development was to ensure portability to most Eiffel compilers and environments. Accordingly, some Eiffel features were used conservatively. Features whose current or future either implementation or behaviour are uncertain were avoided.
An important issue is system-level validity At the time of writing, a new scheme to solve this problem is being worked out by NICE, the Eiffel consortium, this should make this problem much easier to deal with, although the current proposed system may break the design of some existing Eiffel systems. The guidelines followed here should though enable a swift transition to the new system. which is designed to statically detect type errors in cases when error detection is not trivial -- that is, basically, when (1) a feature's export status is restricted in a descendant class, or when (2) the parameters of a function feature are redefined covariantly. Therefore, to prevent future problems, these features were used carefully, only when they proved necessary -- though accidental misuses may remain, as they are difficult to detect because no current compiler issues warnings in such cases, which hopefully can usually be fixed easily without change to program design when discovered. A consequence is a conservative use of anchors -- the keyword like -- as they imply system-level validity issues in most cases.
Another guideline that has been followed is to avoid using features of Eiffel which seemed either redundant or clumsy. Things that can be done better in one way but can be done in two or more different ways, are better done consistently all the time.
One of the nice features of Eiffel is that it makes semicolons optional. Semicolons are used only between method parameters and when they are strictly required by the context, which is an extremely rare occurrence. It makes the source text more readable and solves the dilemma of C-style (end of instruction) versus Pascal-style (instruction separator) use of semicolons.
The features which are completely avoided include parameter anchors Typically the result of a function anchored to a parameter. See the validity rule VTAT, paragraph 2 in [meyer92]. which introduce an odd kind of overloading and may have system validity consequences. The only case of parameter anchors use is as a client of GENERAL for the feature clone which regrettably uses it.
Free operators are also completely avoided, as the need for them was never encountered -- the named method was always preferred when choice was available as a client, such as item versus the operator "@" in the kernel class ARRAY.
Replication under repeated inheritance -- when the keyword select is needed -- was used only when necessary, that is when calling the parent's version of a redefined feature.
The balancing rule -- the automatic promotion to higher precision for a few chosen numeric types -- would have been avoided if the kernel standard had provided a way to avoid it in a portable manner.