DIS-Java-VRML: Coding Style and Documentation Style

Coding Style and Documentation Style

Introduction

This page is intended at developers who are willing to bring their contribution to the dis-java-vrml group.
It aims at providing guidelines for the coding style as well as a documentation style.
For the moment, we are mostly concerned by the documentation style of the javadoc comments, which determine the html documentation generated.
Those guidelines stands for recommendations for the dis-java-vrml package release 1.0.

Naming conventions

Naming for new classes need to match the existing classes. Classes begin with a capital letter, methods begin with a lower case letter. Multiple words added together are only capitalized in the first letter of each word, to improve readability. Constants are usually named in all capital letters. Accessor methods should follow the getVariable/setVariable naming convention.

Code conventions

Well for the moment, just code as you prefer (i.e.: choose readability for you !).
If you don't know how to be readable you can refer to Java code conventions document.
This document might serve as a reference to the group.
tip:
The template document that comes in the next section provides you with a few guidelines on how to layout Javadoc comments next to class, interface, class variables and methods.
You should stick to this layout as close as possible.

Code commenting conventions

For the moment, the only required comment is to include the following header:

/*
 File :<?filename?>.java
 Compiler: jdk 1.3
 */

The rest of the code comments are up to the developers, the only advice might be:
make it clear and understandable, don't be afraid of inserting additional comments...

Javadoc conventions:

The Dis-java-vrml working group will base most of its documentation on Javadoc documentation.
Hence it is critical to define a documentation template stating the format of the Javadoc comments that we generate a uniform HTML API documentation.
For those who know nothing about javadoc, you can refer to the Javadoc Home Page.
You should respect as much as possible the following the guidelines.

Respect as much as possible the format of the style template
In order to improve readability, Javadoc comments should:
- be indented at the same level as the bloc they are commenting
- be preceded by a white line (suggestion for readability)
- directly followed by the commented bloc (if there is another bloc in-between, Javadoc can't find the comment).
- the different sections in a Javadoc should be separated by an empty line for readability, except for respectively the :
  - (author, version ) tag group in the class comment
  - (parameter, return, throws) tag group in the methods/constructors comment.
  - see tag group at the end of all Javadoc comment.
  - short and detailed description section for the class variable and the method/constructor comments.
- a Javadoc built-in tag comment is always at the beginning of a new line, it can be preceded by "*" or by tab/spaces, javadoc recognize (it is not for readability, it is the syntax of javadoc...)
  - Their syntax is :
    " @tag <tag comment>"
There should be a javadoc comment for each (* indicates that the section is "optional", it can be suppressed if there is no real need for it):
- Class containing the following sections order
  - a location section stating where the source comes from.
  - a hierarchy diagram section with a thumbnail linked to an image or showing the inheritance dependence of all the class of the package.
  - a one sentence summary section.
  - a author javadoc built-in tag.
  - a version javadoc built-in tag.
  - a detailed explanation of why the class has been created and what it is used for, plus implementations details.*
  - a history section stating at each entry line: the date, the author and the content of the change.
  - a references section where the user can find some bibliographical or on line references.*
  - one or more see javadoc built-in see tag to route the user towards useful packages.*
- Interface containing in order: (Same as previous)
- Protected/Public Class Variable containing in order:
  - a one sentence (javadoc extracts it from the first line of the comment!) explanation shortly explaining what this variable is.
  - a more detailed explanation section (no white line before it).*
  - zero or more see tag to route the user towards useful packages (it is useless to introduce links to classes quoted in the javadoc comment of the present class).*
- Protected/Public Method containing in order:
  - a one sentence (javadoc extracts it from the first line of the comment!) explanation shortly explaining what the method does.
  - a more detailed explanation section if necessary (no white line before it).
  - zero or more param tag explaining what the parameters have to be (including their range if there are bound to certain values).
  - zero or more exception tag describing what kind of exception and when an exception is thrown by this method .
  - zero or one return tag that describes the returned object.
  - zero or more see tag to route the user towards useful packages (same comment as in the class variable javadoc comments; besides it is useless to provide a link to overridden methods).* NB:
    You have to comment every existing parameter of the signature, as well as the returned parameter, except in case of a void signature.
- Constructors (same as previous)
It is critical to respect the html tags inserted in the javadoc comment of the class see the template document for more information.
- Concerning the html tags the idea is to generate a list of items with an indented content, that's why we widely use the <dl>,<dt> and <dd> which generates a list of definitions items.
  (to be continued...)
Using the javadoc command (on windows):
the current syntax used is : javadoc *.java -author -version -verbose
author and version options stands for taking account respectively of the version number and the author tag.
Verbose stands for debugging, which can be useful in case there might be some weird things.
Note:
If you have private class, it won't generate any documentation.
by default, if you don't declare your class public, javadoc considers it as private, hence won't generate documentation.

You should not have variables and methods with the same name, otherwise, javadoc might link the variable in the index to the method of the same name. As you see, this "grammar" is not straight forward, so the best way to respect it is to use the template file, suppress the sections that are useless and duplicate those that have to be duplicated.... However there is still a lot of room for maneuver and most of the time it is up to developers (or "commentators" to decide of the relevancy of the comment).
It is still a work in progress so it is.

How to use the API

How can I find a Pdu, a Record, a field:

Record :

Usually, Records are encapsulated in public class.
Convention:
Name.java
Where "Name" should be the compound name of the Pdu as defined in the specification without space between words.
The first letter of each word is capitalyzed.
Access all the Pdu names here : link 2 class hierarchy file....
Nb:
Some Record have not been implemented or have been flattened in pdus, see .... for reference.

Pdu

Usually, Pdus are encapsulated in public class. All the fields and records are declared protected.
Convention:
NamePdu.java
Where "Name" should be the compound name of the Pdu as defined in the specification without space between words.
The first letter of each word is capitalyzed.
Access all the Pdu names here : link 2 class hierarchy file....
Nb:
Some Pdu have not been implemented, see .... for reference.

Record :

Usually, Records are encapsulated in public class (note that when found as an element of a Pdu it is instanciated as a protected variable).
Convention:
Name.java
Where "Name" should be the compound name of the Pdu as defined in the specification without space between words.
The first letter of each word is capitalyzed.
Access all the Pdu names here : link 2 class hierarchy file....
Nb:
Some Record have not been implemented or have been flattened in pdus, see .... for reference.

Field :

Usually, field are protected instance variable (for safety).
Convention:
myFieldName.java
Where "myFieldName" should be the compound name of the Pdu as defined in the specification without space between words.
The first letter of each word is capitalyzed, except the first one.
Access all the Pdu names here : link 2 class hierarchy file....
Nb:
Some Record have not been implemented or have been flattened in pdus, see .... for reference.

How shall I use the Pdus

Constructor Methods:
They fill in basically all fields with 0.

Accessor methods :
As you already know, records and fields are all protected variables when found in Pdu or record class.
That's why we need some safe access methods to access their value, wether it be to get it or to change it.

Note that sometimes, it is posssible to find some additionnal accessor method in order to access staghtly t a field nested in a record (in turn defined in its own class).
Usually, you will only deals with Pdu, that you will have to fill in or "unwrap".
So you will have somewhere a "myPdu" instance variable, whose fields will interest you...
It is possible to access each field or record within a Pdu.
through the getVariableName method, which returns a full copy of the object (shares no common pointer with the storing object.),
or through the setVariableName method so you set a field or a record of a given Pdu.
To get it:
myPdu.getVariable();
To set it:
myPdu.setVariable(myVariable);
Nb1:
If the field we want to access is implemented in a record class, we can access it in two steps.
To get it:
myField=myPdu.getRecord.getField();

To set it:
myRecord=myPdu.getRecord() ;
myRecord.setField(myField);
myPdu.setRecord(myRecord);
Nb2:
Some Pdus provides direct access methods to fields nested in records, so that the previous syntax turns into:
myPdu.setRecordField(myField) to set a record (which is a bit more straight forward...).
Other methods:
work in progress

What Can I find in the documentation ?

Work in progress.

Where can I find documentation on a method, on a Pdu, a record, a field ?

With the previous section, you should be able to find any existing Pdu, record or field, accessor method you're looking for.
With this section, you should be able to find the information you need about the design of the class hierarchy, the implementation of the DIS protocol,
and information about the Pdu, Records, Fields and their matching classes.
Semantics of the different tags:
Class tags:
Class Hierarchy:
Summary:
Usually the matching comment in the DIS specification
Explanation
:
Home made comments to further explain implementation, semantics, differences with the protocol.
We should not yet provide simulation management comments for the moment....
History:
log on of the Evolution of the class
References:
Provides external references (our main references are the DIS specification and the DIS data dictionary...).

Instance Variable tags:
work in progress
Method tags:
work in progress

11 October 1999 (official NPS disclaimer)
URL: www.web3D.org/WorkingGroups/vrtp/dis-java-vrml/StyleGuide.html

feedback: brutzman@nps.navy.mil & mcgredo@cs.nps.navy.mil