Contents

Abstract

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

Definitions

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

General conventions about structuring code, Names etc. shall be used as specified in the Ada style guide unless not otherwise specified within this document.

Component Interface

Rules for Object and Object usage

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 ;
private
type Object_Data ;
type Object_Data_Access is access all Object_Data;

type Object is limited tagged record
data : Object_Data_Access := null;
end record;
end X;

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;

.......

begin

Initialize( Q );

.........

Finalize( Q );

end Event_Monitor;

Rules for attribute functions

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

Rules for Methods

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;

begin

if data = null then

raise Not_Initialized;

end if;

.............

exception

when the_Error : Others =>

Error( Exception_Identity( the_Error ), "Insert", data );

end Insert;

Documentation

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.

Interface Specification

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:

• Functional Description
  This section contains the user description of the component. It is intended as a general introduction to the component.
  
• Component Data
  The list of all data items made visible via attribute funtions/procedures and a descritption of the data item. All data type should to be declared within this component.
  
• Methods
  The list of all methods which may be applied to the component. This is simply an overview the complete description shall be done later in the package specification it self
  Note: I am not sure if this is realy an good idea but i am used to it.
  
• Error Handling
  Give a statement about the error handling policy, i. e. explicitly state if exception are catched and stored away for debuging.
  
• Extentsions
  This is an overview of abstract procedures and functions which have to be provided by any implementation of the component and describe the protocoll between the abstract class and the implementation in detail
  Note: This section is very important an should be a part of the component header.
  
• Restrictions
  This section lists all restrictions, .i.e the module is not Y2K or tasking ready..
  Note:
  I think this should done in a way that it possible to retrieve the data automitcaly, i.e.:
  Tasking: No

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

• Description
  A short description of the method. The description is intended for the user of the method. Implementation detailes should not me mentionen, this belongs into the implementation description.
  
• Preconditions
  Preconditions to be met before using the method, i.e. initialize has to be called.
  
• Postconditions
  Note:
  Until now i had no real use for this sections. Should it saty in?
  
• Exceptions
  Exceptions thrown by this method
  
• Note
  Remarks, thinks to be rembered etc...
  

Implemenation Documentation

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.

• Funtional Description
  The functional description is part of the component header an gives an overview about the components, reasons for certain implementation descission and simplifications done during the implementation, references to other documents etc. Dont go to mutch in detail because the implementation is done in the code section, and there the details should be explaint, other wise is is verry mutch possible, that the header is outdated after a small change in the implementation.
  
• Object Data
  This section contains the data where definition of the data where the component is working on. Explain data as comment in this section briefly, i.e:
  
  type Kelvin is new Natural range 0..10000; -- temprature
  type Object_Data is record inner_temp : Kelvin; -- Temperature inside of the house
  outer_temp : Kelvin; -- Temperature outside of the house
  end record;
  
• Methods (procedures and funtions)
  Regardles in which section a method occures, it is proceedetd by an header. The header simply gives a short descritption of the purpose of the procedure. Addtionaly always design descision should be made visible (i.e. binary tree used instead of ..., because ....). A procedure should not be longer then one page including the header. As a result the method will be this simple, that it will be possible to reduce the inline comments in favor of the header to minimum.
  Note:
  I am not sure whether it makes sense impose more rules on this, because in my expierence it quite difficult for even small working groups to keep dicipline (a dsigner is a very strange creature, it behaives normaly like a lone wulf).
  

Templates

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.

References

Annex A - Component specification

Source

Annex B - Component Skeleton

Source

Back to Main Index Contents