Code documentation
Documenting code for whoever takes it over: Javadoc comments and their tags, comments that say why, the README, generated documentation.
- 26 cards
- 5 topics
- Free
The outline, topic by topic
Each topic is weighted the way the exam weighs it.
- Concepts
- Questions
- Sort and link
- Scenarios
- Understand
A few cards from the deck
Documentation comment: what is it?
Show the answer
A comment placed right before a class or a method, written in a form that tools can read to produce the code's documentation.
In Java it opens with
/**. It describes the method's contract (what it expects, what it returns) for whoever calls it without reading its body.The javadoc tool prints the error below. Which fix is needed?
```java
Rem.java:5: error: @param name not found
/**
* Applique une remise.
* @param prix le prix
* @param taux le taux
* @return le prix remisé
*/
public static double appliquer(double prix, double remise)`- Rename the tag to @param remise, as in the signature
- Add a third parameter named taux to the method, so that the tag matches it
- Delete the @return tag, which should not be here
- Add a @throws tag before the faulty parameter tag
Show the answer
Rename the tag to @param remise, as in the signature
The documentation kept the parameter's old name. Javadoc compares the tags to the signature, hence the error; it also reports the gap:
warning: no @param for remise.A good comment says … the code makes this choice; what the line does, the code already says through its ….
Show the answer
A good comment says why the code makes this choice; what the line does, the code already says through its names.
A comment that paraphrases the line must be maintained along with it and ends up contradicting it. A clearer variable or method name is better.
Javadoc: what is it?
Show the answer
A JDK tool that reads the documentation comments of Java code and generates HTML pages from them, reporting wrong tags.
It checks consistency with the signature: an
@paramtag for a parameter that does not exist gives the error@param name not found.The description of a Java library's methods, kept in a separate document, has contradicted the code for months. What should you do?
- Reread the document from start to finish every year and fix all the most significant gaps found
- Delete the document and write nothing more about how it works
- Ask users to report the errors they come across
- Put it in comments above the signatures and generate it at every build
Show the answer
Put it in comments above the signatures and generate it at every build
Documentation lives closest to the code it describes: whoever edits a signature sees the comment, and the tool flags stale tags. Generated documentation is thus rebuilt every time.