How to Write Good CommentsWrite for your audienceInternal commentsGood code requires few commentsGood uses of internal commentsjavadocSlide 7Contractsjavadoc is a contractKnow where to put comments!javadoc comment styleHTML in doc commentsIdentifiers in doc commentsCode in doc commentsTags in doc commentsKeep comments up to dateDocument nearly everythingthis objectParenthesesThe first sentence is specialRules for writing summariesInclude examplesInput and output conditionsBugs and missing featuresWho cares?Aren’t these just arbitrary conventions?When do you add comments?Vocabulary IVocabulary IIThe EndJan 14, 2019How to Write Good Comments2Write for your audienceProgram documentation is for programmers, not end usersThere are two groups of programmers, and they need different kinds of documentationSome programmers need to use your codeDo not explain to them how your code works--they don’t care and don’t want to knowTell them what your methods do, how to call them, and what they returnJavadoc is the best way to document your code for usersOther programmers need to maintain and enhance your codeThey need to know how your code worksUse internal comments for these programmersWhen you work on your program, you are in both groupsDocument as though, the next time you see your program, you will have forgotten everything about it!3Internal commentsUse internal comments to:Explain the use of temporary variablesLabel closing braces in deeply nested statements, or when many lines are between the open and close braceswhile (i != j) { ... ... ... ... ... ... } // end whileExplain complex or confusing codeExplain what the next section of code doesNever repeat the code!count = count + 1; // add one to count4Good code requires few commentsUse internal comments to:Explain the use of temporary variablesBetter: Give them self-explanatory namesLabel closing braces in deeply nested statements, or when many lines are between the open and close bracesBetter: Don’t nest statements that deeplyBetter: Keep your methods shortExplain complex or confusing codeBetter: Rewrite the codeIf it’s complex or confusing, it’s probably buggy as wellExplain what the next section of the method doesBetter: Make it a method with a self-explanatory name5Good uses of internal commentsUse internal comments:If you really can’t make the code simple and obviousTo reference a published algorithmTo mark places in the code that need workEclipse provides three tags for this purpose (you can add more):TODO – Means: This code still needs to be writtenFIXME -- Means: This code has bugsXXX -- Means: I need to think about this some moreTo see these, choose Window --> Show View --> TasksTo indicate an intentional flow-through in a switch statementTo temporarily comment out code (Eclipse: control-/)6javadocjavadoc is a separate program that comes with every Java installationjavadoc reads your program, makes lists of all the classes, interfaces, methods, and variables, and creates HTML pages displaying its resultsThis means javadoc’s generated documentation is always accurateYou can write special documentation (“doc”) commentsYour doc comments are integrated into javadoc’s HTML pageIt’s your job to ensure these are also accurateJavadoc’s output is very professional lookingThis makes you look goodIt also helps keep your manager from imposing bizarre documentation standards7javadocAlways use doc comments to describe the API, the Application Programming InterfaceDescribe all the classes, interfaces, fields, constructors, and methods that are available for usejavadoc can be set to display:only public elementspublic and protected elementspublic, protected, and package elementseverything--that is, public, protected, package, and private elementsRemember, doc comments for the programmer who uses your classesAnything you want to make available outside the class should be documentedIt is a good idea to describe, for your own use, private elements as well8Contracts“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 by Allan Vermeulen and 6 others9javadoc is a contractIn the “real world,” almost all programming is done in teamsYour Javadoc is a contract between you and the other members of your teamIt specifies what you expect from them (parameters and preconditions)It specifies what you promise to give them in returnDo not be overly generous!Provide what is really needed, but...Remember that anything you provide, you are stuck with debugging, maintaining, and updatingProviding too much can really hamper your ability to replace it with something better someday10Know where to put comments! javadoc comments must be immediately before:a classan interfacea constructora methoda fieldAnywhere else, javadoc comments will be ignored!Plus, they look silly11javadoc comment styleUse 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) { // p lines up with the / in /**12HTML in doc commentsDoc comments are written in HTMLIn a doc comment, you must replace: < with < > with > & with & ...because these characters are special in HTMLOther things you may use: <i>...</i> to make something italicExample: This case should <i>never</i> occur! <b>...</b> to make something boldface <p> to start a new paragraphOther types of comments are not in HTML13Identifiers in doc commentsWrap keywords and the names of variables and methods with <code> . . . </code> tagsExample: /** * Sets the <code>programIsRunning</code> flag * to <code>false<code>, thus
View Full Document
Unlocking...