Internal Documentation ConventionsKinds of commentsKinds of internal commentsWhich kind of internal comment?Explaining the code IExplaining the code IIEnd-line comments IEnd-line comments IIUnresolved issuesIntentionally missing breakLabel empty statementsDon’t repeat the codeUse the active voiceDebugging statementsThe EndInternal Documentation ConventionsKinds of comments•javadoc (“doc”) comments describe the user interface:–What the classes, interfaces, fields and methods are for–How to use them•Obviously, the maintainer needs to know what the code does•In addition, the maintainer needs to understand how the code worksKinds of internal comments•“Standard” (C-style) comments: /* ... */•One-line and end-line comments:// a one-line comment is on a line by itselfx = 0; // an end-line comment follows code–These are both “internal” comments, seen only by someone looking at your code–Internal comments are only for maintainers–But avoid things that would embarrass you to a user!Which kind of internal comment?•Rule 36: Use “standard” (/*...*/) comments to comment out code without removing it.•I don’t agree–Suggested because it’s usually easy to do, but...–BlueJ’s comment and uncomment commands make it easier to use one-line (//...) comments–Standard comments cannot be nested, so it’s tricky commenting out code with comments•One-line comments don’t have this problemExplaining the code I•Rule 59: Add internal comments only if they will aid in understanding your code.•Don’t repeat the javadoc comments•Don’t put in comments to explain things that are obvious from the code•Don’t put in irrelevant or useless comments // Diamondbacks beat the Yankees, 3 - 2•Always put comments before the code they describe, never after the codeExplaining the code II•Rule 37: Use one-line comments to explain implementation details.•One-line comments are also good for writing reminders for yourself about things you still need to work on // need to rewrite this if more than one rabbit•I like to use one-line comments to tell what the next block of code is going to do // put the rabbit in a random locationEnd-line comments I•Rule 61: Avoid the use of end-line comments.–This rule is largely to prevent overly long lines–But: Rule 62: Explain local variable declarations with an end-line comment. int edgeDistance; // distance to the nearest edge–And: Rule 64: Label closing braces in highly nested control structures. } // end switch } // end if } // end for j} // end for iEnd-line comments II•I also find end-line comments useful for an else that is a long way from its if: if (distance > 5) { a lot of code in between}else { // distance <= 5 ...}Unresolved issues•Rule 63: Establish and use a set of keywords to flag unresolved issues.–I personally like to use $$•// $$ the canvas isn't being redrawn properly–More specific flags are likely to be used in large projectsIntentionally missing break•Rule 65: Add a “fall-through” comment between two case labels of a switch statement, if no break statement separates those labels.–The switch statement is so badly designed that forgetting the break is a common error–To keep an intentionally missing break from being “corrected,” add a commentLabel empty statements•Sometimes you intentionally use a loop with an empty statement body•Rule 66: Label empty statements. while ((c = reader.read()) == space) ; // Empty body•I prefer a different solution: use an empty block as the statement body while ((c = reader.read()) == space) { }Don’t repeat the code•Rule 60: Describe why the code is doing what it does, not what the code is doing.•Another way of saying this is:Comments should not echo code.–Here’s a typical example of a bad comment: count = 0; // set count to zero•You should assume that anyone reading your internal comments knows some Java!Use the active voice•Rule 34: Use the active voice, and omit needless words–// zero out the array–// each of the elements of the array is set to// zero by the following loop•Writing comments is still writing--all the rules for good writing apply to comments•Best reference: The Elements of Style, by Strunk and WhiteDebugging statements•We sometimes put in debugging statements that we plan to remove afterwards•Simple trick: start these “temporary” statements in the first column, so you can find them easily boolean legalLocation(int row, int col) {System.out.println("legalLoc " + row + " " + col); return row >= 0 && row < numRows && column >= 0 && column < numCols; }The
View Full Document
Unlocking...