last updated 12.09.99
Status: For Review
This documents summarises the some coding rules for ACDE-Components. The design process yielding the imput for the coding process is described in the document "Design Guidlines for ACDE Components" .
A component is an Ada95 package which provides a data type and operations on this data type, which is always named as Object . The structure of the Object is hidden in the component it self. The operations are split into attribute operations and methods.
Attribute operations are used to set or query values of attributes. As a general rule, such an operation has no side effects and it does not change the state of the object it self.
Methods do change the state of the component, and do have side effects.
General conventions about structuring code, Names etc. shall be used as specified in the Ada style guide unless not otherwise specified within this document.
The contents of the object data should be made invisible to the component user in order to prevent him to make assumptions about the implementation of the component. As a result the object data shall always be implmented in the following way:
package X is
type Object is limited tagged private;
type Handle is access all Object'Class ;
type Object_Data ;
type Object_Data_Access is access all Object_Data;
type Object is limited tagged record
data : Object_Data_Access := null;
The completion of the Object_Data is defered to the package body. The data pointer is assumed to be set by the Initialize procedure. The package name should represent the object name in order to make the application code more readable.
procedure Event_Monitor is
Q : Event_Q.Object;
Initialize( Q );
Finalize( Q );
Attributes have to be set and queried. Attribute functions should always named as the attribute it self. The typical attribute operations will look like this:
procedure Temperature( this : in out Object; value : Degrees_Celsiius );
function Temperature( this : in Object ) return Degrees_Celsius
The name of a method should be some what reasonable, which means it should be named in line with the action performed on the data, i.e. Insert, Set, Add, Delete, Open etc. The first parameter of the method always is an instance of the object.
procedure Insert( this : in out Object; data : Some_Record ) is
data : Object_Data_Access := this.data;
if data = null then
when the_Error : Others =>
Error( Exception_Identity( the_Error ), "Insert", data );
There are two kinds of documentation, the interface description and the implementation description .
The interface description is part for the package specification. The focus of the contents of the interface description is to provide information for user of the package.
The implementation description is part of the package body and it focuses on giving help to the software designer responsible for the component it self.
The Interface specification for a component (see Annex A for a template) consits of a global header and the and the method specification.
The global header contains the following sections:
The method specification is done within the package specification it self. Every procedure/functions supplied by the component is preceedet by the following comment block:
--| Description :
--| Preconditions :
--| Postconditions :
--| Exceptions :
--| Note :
A Component skeleton is shown in Annex B. The documentation consists basicaly of a header in front of the component and several sections of code. In general if not otherwise specified follow the style guide for Ada95.
Templates are available in Annex A and Annex B. This requires that there is a binding between an ACSII Text viewer and *..adb, *.ads, or you can simply download the stuff to your home directory.
The Template are always part of the latest snapshot available via the download page.
Back to Main Index Contents