The instructions do read "all classes and interfaces" so I'm taking it at face value and documenting everything. It's a little bit more writing, but I tend to write most of the comments first, so no big deal. I do, by the way, have private inner classes (ActionListeners.)
javadoc has the -public, -protected, -package and -private switches to determine what javadoc generates documentation for. Per the previous comment, I'm thinking I have to use -private.
Regards, Jay [ October 15, 2004: Message edited by: Jay Bromley ]
The following is from the documentation sub-section within the Application Overview of my instructions.
The code itself should be as clear as possible; do not provide comments that do not add to the comprehensibility of the code. Awkward or complex code should have descriptive comments, and javadoc style comments must be used for each element of the public interface of each class. You must create a full suite of documentation for the classes of the completed project. This must be generated using the tool "javadoc" and must be in HTML format. Provide javadoc documentation for all classes you write...
I think commenting the 'public interface' is the way forward :-)
Awkward or complex code should have descriptive comments, and javadoc style comments must be used for each element of the public interface of each class.
Provide javadoc documentation for all classes you write...
It is contradicting itself. Even so I think that only public interface classes and methods need to be documented with Javadoc, private methods and classes should be anonymous to the clients of the code in any respect, after all this is one of the main points of object orientation.
..and not for the first time I'm sure you'll agree! :roll:
I think this is the 'common sense' solution though. You could even document the decision to document!
p.s. I'm currently reading Refactoring: Improving the Design of Existing Code by Martin Fowler. It's a good read that encourages the development of self describing code. i.e. Only put comments (non-javadoc) where necessary for clarity and if they're needed at all then the first step is probably to assess why the code is so complex as to not be readable. Bit off subject but this reminded me of it