Coding Guidelines for ACDE Components

Michael Erdmann

last updated 12.09.99

Status: For Review


  • Abstract
  • Defintions
  • General Conventions
  • Rules for Object and Object usage
  • Component Interface
  • Rules for Attribute procedures
  • Rules for Methods
  • User Documentation
  • Interface Specification
  • Functional Description
  • Component Data
  • Methods
  • Error Handling
  • Extensions
  • Restrictions
  • Implementation Documentation
  • Functional Description
  • Component Data
  • Methods
  • References
  • Templates
  • Annex
  • Annex A - Package specification
  • Annex B - Package body
  • 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" .


    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
    Object is limited tagged private;

    Handle is access all Object'Class ;

    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;



    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 :=;


    if data = null then

    raise Not_Initialized;

    end if;



    when the_Error : Others =>

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

    end Insert;


    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:

    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 :

    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.


    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.


  • [1] J.E Hollingsworth - Software Component Design for Reuse: A Language Independant Discipline Applied to Ada. Ohio State University
  • Annex A - Component specification


    Annex B - Component Skeleton


    Back to Main Index Contents