Doc Comment Conventions Write for your audience Rule 32 Write documentation for those who must use your code Users should not need to care how your code works those who must maintain your code Maintainers need to understand your code These two groups of people require different kinds of documentation javadoc is the best way to document for users use internal comments to explain how it works javadoc javadoc is a separate program that comes with every Java installation javadoc reads your program makes lists of all the classes interfaces methods and variables and creates an HTML page displaying its results This means javadoc documentation is always accurate Your doc comments are integrated into javadoc s HTML page It s your job to ensure these are also accurate BlueJ includes a limited version of javadoc javadoc Rule 35 Use documentation comments javadoc to describe the programming interface javadoc can be set to display only public things classes methods fields public and protected things public protected and package things everything even private things BlueJ emphasizes simplicity doesn t give options Always write doc comments for the user Contracts The primary purpose for documentation comments is to define a programming contract between a client and a supplier of a service The documentation associated with a method should describe all aspects of behavior on which a caller of that method can rely and should not attempt to describe implementation details The Elements of Java Style Rule 35 Know where to put comments javadoc comments must be immediately before a class an interface a constructor a method a field Anywhere else javadoc comments will be ignored Plus they look silly javadoc comment style Rule 42 Use a single consistent format and organization for all documentation comments This is where the text starts The star lines up with the first star above there is a space after each star The first sentence is the most important it becomes the summary tag these go at the end after a blank line void myMethod this lines up with the in HTML in doc comments Doc comments are written in HTML In a doc comment you must replace with lt with gt because and indicate tags in HTML Other things you may use i i to make something italic Example This case should i never i occur b b to make something boldface p to start a new paragraph Other types of comments are not in HTML Identifiers in doc comments Rule 43 Wrap keywords identifiers and constants with code code tags Example Sets the code programIsRunning code flag to code false code thus causing code run code to end the Thread doing the animation Code in doc comments Rule 44 Wrap code with pre pre tags Preformatted text is shown in a monospaced font all letters the same width like Courier and keeps your original formatting indentation and newlines Preformatted text is also good for ASCII drawings pre NW N NE W E SW S SE pre Tags in doc comments I Rule 46 Establish and use a fixed ordering for javadoc tags In class and interface descriptions use author your name version a version number or date Use the author tag in your assignments In method descriptions use param p A description of parameter p return A description of the value returned unless it s void exception e Describe any thrown exception Tags in doc comments II Rule 54 Fully describe the signature of each method The signature is what distinguishes one method from another the signature includes the number order and types of the parameters Use a param tag to describe each parameter param tags should be in the correct order Don t mention the parameter type javadoc does that Use a return tag to describe the result unless it s void Keep comments up to date Rule 33 Keep comments and code in sync An incorrect comment is often worse than no comment at all Rule 38 Describe the programming interface before you write the code It s better to decide what to do then do it than it is to do something then try to figure out what you did Document nearly everything Rule 39 Document public protected package and private members Personally I don t see much need to document private variables provided they have good meaningful names Rule 40 Provide a summary description and overview for each package In other words tell what your program does this object Rule 52 Use this rather than the when referring to instances of the current class In Java this is a keyword that refers to the instance of this class that is responding to the message that is the instance that is executing the method Hence this object has an especially clear meaning in comments Example Decides which direction this fox should move Parentheses C and C programmers pay attention Rule 52 Do not add parentheses to a method or constructor name unless you want to specify a particular signature If in a comment you refer to turn you are implying that turn is a method with no parameters If that s what you meant fine If that s not what you meant say turn instead Why is this different from C and C In C method overloading is not allowed C programming is strongly rooted in C Write summaries Rule 53 Provide a summary description for each class interface field and method The first sentence in each doc comment is special it is used as the summary sentence javadoc puts summaries near the top of each HTML page with a link to the complete doc comment further down the page Rule 48 Write summary descriptions that stand alone Rules for writing summaries Rule 49 Omit the subject in summary descriptions of actions or services Rule 47 Write in the third person narrative form Good Finds the first blank in the string Not as good Find the first blank in the string Bad This method finds the first blank in the string Bad Method findBlank String s finds the first blank in the string Include examples Rule 55 Include examples I think this rule should read Include examples if they are helpful Most methods should be simple enough not to need examples Sometimes an example is the best way to explain something Input and output conditions Rule 56 Document preconditions postconditions and invariant conditions A precondition is something that must be true beforehand in order to use your method Example The rabbit must be alive A postcondition is something that your method makes true Example The rabbit is not against an edge An invariant is something that must always be true about an object Example The rabbit is in a valid row and column Bugs and missing features Rule 57 Document known
View Full Document
Unlocking...