How to Write Good Comments Jan 14 2019 Write for your audience Program documentation is for programmers not end users There are two groups of programmers and they need different kinds of documentation Some programmers need to use your code Other programmers need to maintain and enhance your code Do not explain to them how your code works they don t care and don t want to know Tell them what your methods do how to call them and what they return Javadoc is the best way to document your code for users They need to know how your code works Use internal comments for these programmers When you work on your program you are in both groups Document as though you will have forgotten everything by tomorrow 2 Internal comments Use internal comments to Explain the use of temporary variables Label closing braces in deeply nested statements or when many lines are between the open and close braces while i j end while Explain complex or confusing code Explain what the next section of code does Never repeat the code count count 1 add one to count 3 Good code requires few comments Use internal comments to Explain the use of temporary variables Label closing braces in deeply nested statements or when many lines are between the open and close braces Better Don t nest statements that deeply Better Keep your methods short Explain complex or confusing code Better Give them self explanatory names Better Rewrite the code If it s complex or confusing it s probably buggy as well Explain what the next section of the method does Better Make it a method with a self explanatory name 4 Good uses of internal comments Use internal comments If you really can t make the code simple and obvious To reference a published algorithm To mark places in the code that need work Eclipse provides three tags for this purpose you can add more TODO this code still needs to be written FIXME this code has bugs XXX I need to think about this some more To see these choose Window Show View Tasks To indicate an intentional flow throw in a switch statement To temporarily comment out code Eclipse control 5 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 HTML pages displaying its results You can write special documentation doc comments This means javadoc s generated documentation is always accurate Your doc comments are integrated into javadoc s HTML page It s your job to ensure these are also accurate Javadoc s output is very professional looking This makes you look good It also helps keep your manager from imposing bizarre documentation standards 6 javadoc Always use doc comments to describe the API the Application Programming Interface Describe all the classes interfaces fields constructors and methods that are available for use javadoc can be set to display only public elements public and protected elements public protected and package elements everything that is public protected package and private elements Remember doc comments for the programmer who uses your classes Anything you want to make available outside the class should be documented It is a good idea to describe for your own use private elements as well 7 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 8 javadoc is a contract In the real world almost all programming is done in teams Your Javadoc is a contract between you and the other members of your team It specifies what you expect from them parameters and preconditions It specifies what you promise to give them in return Do not be overly generous Provide what is really needed but Remember that anything you provide you are stuck with debugging maintaining and updating Providing too much can really hamper your ability to replace it with something better someday 9 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 10 javadoc comment style Use this format for all doc comments This is where the text starts The asterisk lines up with the first asterisk above there is a space after each asterisk The first sentence is the most important it becomes the summary param x Describe the first parameter don t say its type param y Describe the first parameter don t say its type return Tell what value is being returned don t say its type public String myMethod int x int y lines up with the in 11 HTML in doc comments Doc comments are written in HTML In a doc comment you must replace with lt with gt with amp because these characters are special 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 12 Identifiers in doc comments Wrap keywords and the names of variables and methods 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 13 Code in doc comments 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 14 Tags in doc comments Use the standard 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 the method returns void exception e Describe any thrown exception 15 Keep comments up to date Keep comments accurate An incorrect comment is worse than no comment Any time you change the code check whether you need to change the comment Write the doc comments 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 16 Document nearly everything If it s available outside the class document it If it s private to the class it s still a good idea to document
View Full Document
Unlocking...