Use 45 minutes to add JavaDoc comments to a one or more of the central classes you are using in your project. If you do not have such classes yet simply try to write the interface, i.e., the methods that you assume will be in the interface and add JavaDoc comments to this skeleton.
Generate the JavaDoc for the class(es) you have documented and send the documentation to your buddy group. In return you will get the JavaDoc for the class(es) that the buddy group has made. Use 15 minutes to study the documentation that the buddy group has provided to you. This should be done in your group room without the buddy group being there. Write down what you find is good and bad in the documentation. This could for example be answering the following questions (feel free to answer more questions).
Do the fields and methods have saying names?
Do each method perform one well-defined task?
Do all method have an obvious and clear parameter signature and return value?
Are all parts of the program documented (data fields, methods, parameters, constants, exceptions, constructors, return value, authors, version, history, when created, etc.)?
Is the documentation readable?
Is the documentation consistent?
Is the documentation too detailed?
Are examples provided for the most difficult (or non-obvious) methods in the interface?
Could you write a program that would use the software without having to consult the buddy group?
Meet with the buddy group and use 2 x 15 minutes to give feedback on the documentation.
The groups and buddy groups are the following.Group One (will meet in this group room) |
Group Two (buddy group) |
---|---|
E1-207 | E1-209 |
E2-107 | E2-115 |
E1-113 | E2-203 |
E4-101 | E4-103 |
E4-105 | E4-211 |
E4-212 | E4-213 |
E3-104 | E3-106 |
E3-108 | E3-110 |
E3-114 | E3-116 |
E1: Discuss the strengths and weaknesses of using JavaDoc. Should more types of documentation be added to JavaDoc? Can any documentation be removed because it is obvious? (hint: think how are "real-world" programs used and maintained).
Best regards,
Kristian Torp