DOC PREVIEW
Penn CIT 591 - Doc Comment Conventions

This preview shows page 1-2-3-25-26-27 out of 27 pages.

Save
View full document
View full document
Premium Document
Do you want full access? Go Premium and unlock all 27 pages.
Access to all documents
Download any document
Ad free experience
View full document
Premium Document
Do you want full access? Go Premium and unlock all 27 pages.
Access to all documents
Download any document
Ad free experience
View full document
Premium Document
Do you want full access? Go Premium and unlock all 27 pages.
Access to all documents
Download any document
Ad free experience
View full document
Premium Document
Do you want full access? Go Premium and unlock all 27 pages.
Access to all documents
Download any document
Ad free experience
View full document
Premium Document
Do you want full access? Go Premium and unlock all 27 pages.
Access to all documents
Download any document
Ad free experience
View full document
Premium Document
Do you want full access? Go Premium and unlock all 27 pages.
Access to all documents
Download any document
Ad free experience
Premium Document
Do you want full access? Go Premium and unlock all 27 pages.
Access to all documents
Download any document
Ad free experience

Unformatted text preview:

Doc Comment ConventionsWrite for your audiencejavadocSlide 4ContractsKnow where to put comments!javadoc comment styleHTML in doc commentsIdentifiers in doc commentsCode in doc commentsTags in doc comments ITags in doc comments IIKeep comments up to dateDocument nearly everythingthis objectParenthesesWrite summariesRules 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 End1Doc Comment Conventions2Write 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”3javadoc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 javadoc4javadoc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 of your classes (a programmer)5Contracts“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)6Know 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 silly7javadoc 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 /**8HTML 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 HTML9Identifiers 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. */10Code 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>11Tags 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.12Tags 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)13Keep 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 did14Document 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!15this 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. (As a comment in the Fox class)16Parentheses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 C17Write 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


View Full Document

Penn CIT 591 - Doc Comment Conventions

Documents in this Course
Stacks

Stacks

11 pages

Arrays

Arrays

30 pages

Arrays

Arrays

29 pages

Applets

Applets

24 pages

Style

Style

33 pages

JUnit

JUnit

23 pages

Java

Java

32 pages

Access

Access

18 pages

Methods

Methods

29 pages

Arrays

Arrays

32 pages

Methods

Methods

9 pages

Methods

Methods

29 pages

Vectors

Vectors

14 pages

Eclipse

Eclipse

23 pages

Vectors

Vectors

14 pages

Recursion

Recursion

24 pages

Animation

Animation

18 pages

Animation

Animation

18 pages

Static

Static

12 pages

Eclipse

Eclipse

23 pages

JAVA

JAVA

24 pages

Arrays

Arrays

29 pages

Animation

Animation

18 pages

Numbers

Numbers

21 pages

JUnit

JUnit

23 pages

Access

Access

18 pages

Applets

Applets

24 pages

Methods

Methods

30 pages

Buttons

Buttons

20 pages

Java

Java

31 pages

Style

Style

28 pages

Style

Style

28 pages

Load more
Download Doc Comment Conventions
Our administrator received your request to download this document. We will send you the file to your email shortly.
Loading Unlocking...
Login

Join to view Doc Comment Conventions and access 3M+ class-specific study document.

or
We will never post anything without your permission.
Don't have an account?
Sign Up

Join to view Doc Comment Conventions 2 2 and access 3M+ class-specific study document.

or

By creating an account you agree to our Privacy Policy and Terms Of Use

Already a member?