Coding Assignment Help on Project 3 – Play Tetris
Coding Assignment Help on Project 3 – Play Tetris
Commenting guidelines
Documenting Your Classes and Methods
It is important always to document your code clearly. For Java programmers, some general commenting conventions have been established by a tool called javadoc (Links to an external site.)Links to an external site., the Java API documentation generator. This tool can automatically extract documentation comments from source code and generate HTML class descriptions, like those in the Sofia API (Links to an external site.)Links to an external site.. This tool is so popular and so commonly used that it has set the standard for how people document the externally visible features in their Java code. (See the Sun article on “How to Write Doc Comments for the Javadoc Tool” (Links to an external site.)Links to an external site..) (Coding Assignment Help on Project 3 – Play Tetris)
JavaDoc (Links to an external site.)Links to an external site. Comments
The javadoc tool expects comments to be written in a particular way–other comments are ignored. JavaDoc comments (also called just “doc comments”) always start with “/**” and end with “*/“. Any other comments are ignored when generating documentation for your code. Further, a JavaDoc comment describing something always appears immediately before the thing it documents.
Within a JavaDoc comment, special tags can be embedded to signal particular kinds of information. These doc tags enable complete, well-formatted API documentation to be automatically generated from your source code. All JavaDoc tags start with an at-sign (@).
If you already know some HTML, you can even embed simple HTML markup inside your JavaDoc comments, and it will appear in the generated documentation for your classes. This is handy if you want to add bullet lists in a class description, or wish to make part of your comment stand out in boldface, and so on.
Describing a Class
You should place a descriptive JavaDoc comment just before the start of each class you write:
/**
* Write a one-sentence summary of your class here.
* Follow it with additional details about its purpose, what abstraction
* it represents, and how to use it.
*
* @author Stephen Edwards (stedwar2)
* @version 2011.01.30
*/
public class UserProfile
. . .
{
. . .
}
Class descriptions typically use two tags: @author indicates who wrote the file, and @version indicates the “version” of this file or project. You can use your full name, or just PID, in an @author tag. In this course, it is fine to use the date when the file was written as the version information in the @version tag. (Coding Assignment Help on Project 3 – Play Tetris)
When using tags like @author and @version, make sure to put them at the beginning of the line within the doc comment.
For the @author line be sure to list your user name (PID) as well as your first and last name. Also, if you started off with a default comment generated by the IDE (like the example above) don’t forget to replace the text inside the comment with your own. The javadoc tool will use the very first sentence of your comment as a one-sentence summary of your class, and will use the entire text of your comment as the full class description.
Remember that if you just write regular comments, they won’t be recognized as “official” descriptive text for document generation:
// This comment describes what this class does, but because it
// uses //, it won’t be recognized as a JavaDoc comment.
public class UserProfile
. . .
{
. . .
}
Documenting a Method
You should place a descriptive JavaDoc comment just before each method or constructor you write:
/**
* Move the robot forward to the next HTML heading.
*/
public void advanceToNextHeading()
{
. . .
}
As with other JavaDoc comments, make sure this appears just before the method it describes. For methods that have parameters, you should also include a brief description of what each parameter means. For example, we might have a UserProfile class that provides a setter method for its name:
/**
* Set the profile’s name to the given value.
*
* @param newName The new name for this profile.
*/
public void setName(String newName)
{
. . .
}
Here, a @param tag has been used to give a description of the meaning and use of the parameter. Use a separate @param tag to describe each parameter in the method (or constructor). Be sure to start these tags at the beginning of a comment line, and group all of the tags with the same name together (i.e., all @param tags should be next to each other). (Coding Assignment Help on Project 3 – Play Tetris)
Again, javadoc will take the first sentence in your comment as a one-sentence summary of what the method does. The remainder of the comment will be used in generating a full description of the method.
Some methods have return values–that is, they give back information to their caller. For example, a getName() method might return a String containing the user profile’s current name. You can document what information is returned using a @return tag:
/**
* Get this profile’s name.
*
* @return This profile’s name
*/
public String getName()
{
. . .
}
Generating Your Documentation
Within an Eclipse project, you can use the Project->Generate Javadoc… command to generate full documentation for your own project straight from your source code. Click Next twice, and in the final screen check to “Open generated index file in browser” near the bottom. Once complete, a new tab will open showing all of the generated documentation for your classes.
Other Comments in Your Code
JavaDoc comments are “public” documentation of the externally accessible features of your classes. Often, you may also wish to include “internal” (that is, private) documentation that is only useful to someone reading the source code directly. Any comment that does not begin with /** is treated as private, purely for someone with access to the source code. You are free to use such comments where ever you like to improve the readability of your code, but …
Internal Comments Are the Documentation Technique of Last Resort
Choose all names carefully so that a naïve reader’s first interpretation will always be right. Do not choose names that might mislead someone about what a method is supposed to do, or what information a variable holds. Choosing poor names or convoluted logic structure and then trying to explain it in lengthy comments does little to improve readability. This is doubly true for methods, because half the time a reader will see your method name where it is called, not when they are reading your method itself. If it is not immediately clear what the method should do, that affects the readability of all the code calling this method, no matter how many comments you put in the method itself.
Strive to write code that is clear and understandable on its own, simply by virtue of the names you have chosen and the structure you use. If you feel you have to add an internal comment to explain something, ask yourself what needs explaining. If you need to explain what a name refers to or how you intend to use it, consider choosing a better name. If you have to explain a complex series of if statements or some other convoluted structure, ask yourself (or a TA) if there is a better way. Only after considering these alternatives should you add descriptive comments. (Coding Assignment Help on Project 3 – Play Tetris)
Redundant Comments Are Worse Than No Comments
Consider these comments:
user = new UserProfile(); // Create a new user profile
x = x + 1; // Add one to x
user.setName(“Ben”); // change the profile name
These are examples of useless comments. Many students add comments to their code just to “make sure everything is documented,” or because they believe copious comments are what the instructor is looking for. Comments like this just get in the way of reading the code, however. You should only add comments when they express something that isn’t already evident from the code itself. Comments are more information that the poor reader has to wade through, so you need to carefully balance their benefits against the cost of having to read them. This reader might be – and often will be – you, so a good mental model to adopt is that you are writing comments as messages to your future self. This future you will be more experienced than the current you when it comes to programming, but will have forgotten the details of the code written even a week ago. You should write your comments with an eye towards minimizing the mental effort this future you has to expend to be able to understand and maintain your code. (Coding Assignment Help on Project 3 – Play Tetris)
References
https://www.w3schools.com/java/java_intro.asp
