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 |
Until we get good at this let's use the Basic Naming Convention (see section 18)
- Avoid using the "#pragma prefix" pragma in an IDL file to specify the package name (which can be used by the jidl switch --auto-package). Instead use jidl switch --prefix-package <module> edu.stanford.slac.aida. This will create the files in directory edu.stanford.slac.aida.<module>, and will put a matching package directive at the head of the source files. (Q: Is there a good reason to use #pragma prefix from the C++ perspective instead?).
- module names should be all lower-case (because these will become java package names, which should be all lower-case according to Java conventions)
- interface names should start with Uppercase first letter, because these will become java interface names which have capital initial in Java conventions. We additionally say they should end in capital I to denote an interface.
- method names should be lower case first letter, since they will become class method names, which have lowercase first letter by convention in Java and C++.
java -Dorg.omg.CORBA.ORBClass=com.ooc.CORBA.ORB \ -Dorg.omg.CORBA.ORBSingletonClass=com.ooc.CORBA.ORBSingleton \ MyAppWe 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
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 clients go in package "test", and should import the package which they test (rather than being included with the package which they test).
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.
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) { ...
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.