Comp 110/401 Documentation: Comments

1. Comp 110/401Documentation: Comments Instructor: Prasun Dewan

2. Prerequisite • State Properties

3. Programming Style: The Art of Programming  Use Interfaces  Efficiency Document Program  Avoid Code Repetition  Giving Least Privilege  Use Named Constants

4. Comment? Any code in the program removed by the compiler. Useful for documentation doublebmi;//computed by setWeight and setHeight Also for enclosing debugging code // System.out.println(newHeight);

5. What to Comment? • Any code fragment needing explanation • Class • Top-level algorithm, author, date modified • Variable declaration • Purpose, where used, how its value is computed • Method declaration • params, return value, algorithm, author, date modified • Statement sequence • Explanation • Debugging code Summarizing and/or Elaborating Comments

6. Comment Types Single line comments doublebmi; //computed by setWeight and setHeight Single or multi-line arbitrary comments /* recompute dependent properties */ bmi = weight/(height*height); /* recompute dependent properties */ bmi = weight/(height*height);

7. Removing Debugging Code • System.out.println(newHeight); /*debugging statement */ • /* • System.out.println(newHeight); /*debugging statement */ • */ • /* • System.out.println(newHeight); // debugging statement • */

8. What to Write in a Comment? doublew; // weight Bad variable name doubleweight; // weight Redundant doubleweight; Self-commenting doublebmi; // computed by setWeight and setHeight Useful comment

9. Self Commenting Variable Names public static final int NUMBER_WITH_LARGE_FACTORIAL = 15; Eclipse CTRL-SPACE will complete name for you

10. Method Decomposition Commentlong identifier name publicstaticvoidmodularReadAndPrintStrings() () { String[] strings = readStrings(readNumStrings()); printStrings(strings); printString(strings[0]);// unsafe } Eclipse CTRL-SPACE will complete name for you publicstaticintreadNumStrings() { System.out.println("Number of Strings:"); returnConsole.readInt(); // reads the next line as integer } publicstatic String[] readStrings(intnumElements) { System.out.println("Please enter " + numElements + " strings"); String[] strings = new String[numElements]; // dynamic array for(intelementNum = 0; elementNum < numElements; elementNum++) strings[elementNum] = Console.readString(); returnstrings; } Useful information assuming the reader does not know it

11. For Whom the Comments Toll Other programmers who may have to maintain your code Other programmers using the API provided by your code They do not have the context of the code, so some comments may not be redundant API comments useful in Web Documents and Tooltip Messages in Programming Environment Follow special format so they can be extracted by web doc tools and programming environment

12. JavaDoc Conventions For Headers (API) /** *@authorPrasunDewan *Formore info see: *{@link http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#exampleresult} */ publicinterfaceCommentedBMISpreadsheet { /** *@paramnewValueisthenewvalueofvariableweight *notonlysetsvaluesofweight, *butalsocomputesnewvaluebmiand *assignsittovariablebmi */ public voidsetWeight(doublenewValue); JavaDoc Tags Interface or Class? Interface is the API

13. Example In well written code, difficult to find opportunities to comment Do not comment for the sake of commenting