AIDA Conventions 

 

This page describes the programming guidelines and associated conventions used for Aida development.

Naming Conventions File Name Conventions
Runtime Conventions Documentation Conventions
Basic File System Structure for AIDA JavaDoc Conventions

 

Naming Conventions

Java Basic Naming Conventions

Until we get good at this let's use the Basic Naming Convention (see section 18)

IDL File Conventions

Runtime Conventions

java -Dorg.omg.CORBA.ORBClass=com.ooc.CORBA.ORB \ 
-Dorg.omg.CORBA.ORBSingletonClass=com.ooc.CORBA.ORBSingleton \ 
MyApp

We may choose to enforce this in our code at a later date. See the Orbacus FAQ in \package\aida\tool\orbacus\OB_JOB-4.0.5\Orbacus_FAQ.txt

Basic File System Structure for AIDA

We use a separate IDL module for each servant (da, magnet, name etc). You might ask, why not just different interfaces in one module, like an overall "aida" module. The answer is because an IDL module equates to a java package, and each java package must be in a unique directory. The jidl compiler enforces that by creating a directory for each module it comes across, and putting a "package" statement, with the name of the module, at the top of each file it creates for that module. Correspondingly, the .class files for each package go in their own directory. And this is useful for distributing the servant code, since if each servant's code goes in its own directory, we can easily create a .jar file of the files in that one directory, and deliver that .far file to the machine which is going to host that servant.

Test Programs

Test clients go in package "test", and should import the package which they test (rather than being included with the package which they test).

File Name Conventions

Documentation Conventions

Documentation should be web based and placed in the Aida web site. The web site filesystem location is afs\slac\package\common\doc. There is a template document for Aida web documents in Aida Template Document

JavaDoc Conventions

Please follow the Javadoc documentation conventions and style rules laid out in How to Write Doc Comments for the JavadocTM Tool. . A summary list of tags is here

Additionally, for method documentation, the javadoc comment should be split into functional summary paragraph - similar to the familiar "Abs:" tag we used on VMS, optionally followed by the longer systematic description paragraph(s) corresponding to the Rem: tag we used on VMS. Note that to distinguish paragraphs, javadoc requires the HTML <p>...</p> tag.

Eg:

    /**
     * <p> Maps a query string to a named data item accessible by AIDA. </p>
     * 
     * <p> The mapping is defined the regular expression list stored in the 
     * directory service database 'transform' field. </p>
     *
     * @param query     An AIDA query string
     * @param transform A sed regular expression which defines how to 
     *                  re-write the query to get an Aida accessible data item.
     * @return          An AIDA accessible named data item (or, possibly another
     *                  query).
     */
    private String transformTarget(String query, String mapExpr)
    { ...

CORBA Interfaces

Javadoc for Corba interfaces should give the details of the implementation in the systematic description paragraph:

Eg 

/**
 * <p> Defines the AIDA Directory Service API implementation. <p>
 * 
 * <p> DaNameServiceI_impl implements the DaNameServerI IDL interface. <p>
 */
public class DaNameServerI_impl extends DaNameServerIPOA
{ ...

[Aida Home Page][SLAC Controls Software Group][ SLAC Home Page]

Author:  Greg White, 15-Jul-2001
Modified by: Greg White, 1-Aug-2001. Added Doc Conventions
                        Ron MacKenzie, 1-Jul-2002, Added Table of Contents and Exception Handling and Logging section.