Documentation question

[Victor Bucutea]

Howdy Guys,


I'd like to know what do your Javadoc comments contain?
Do they contain design choices ( advantages/ disadvantages and descriptions ) like the ones below, or they just describe the role of the class and it's usage?

Rephrase.
The javadoc comments should contain comments that another programmer might use to understand those classes, or comments that help the assessor understand the code and the decisions?

  /**
 * Abstract class which handles generic DB file operations. It is not
 * specialized enough to store a specific entity . The entity information ( such
 * as record length and field length) will be provided by the superclass. It
 * provides two big advantages :
 * <ul>
 * <li> having the code which handles persistence and locking in one place, and
 * <b>if we would like to add new entities to store in a flat-file DB, we would
 * implement this class and reuse it's methods </b> </li>
 * <li> it keeps the superclass code cleaner by abstracting the creation of
 * RandomAccessFile and DB initialization
 * </ul>
 */  

[Roel De Nijs]

Hi Victor,

My opinion:
* javadoc = should contain comments that another programmer might use to understand those classes
* choices.txt = comments that help the assessor understand the code and the decisions

Kind regards,
Roel

[Victor Bucutea]

Yep ...


I was kinda expecting that answer . The reason why i asked is that in Andrew's book javadocs describe a lot of design choices.



Victor

[Matheus Mendes]

The reason why i asked is that in Andrew's book javadocs describe a lot of design choices.

Thats a good thing to be in the javadocs too. I mean, you don't need to describe why you choose RMI or why you want to design the GUI like that, but is good to describe how your architeture works. It's a good thing to others programmers read about a system that they will give support and maintenance.

For example, in the Andrew's book he describes how he read a register in the .db file and what the system do to ensure the data consistence.