Using Comments to Document Programs. & What is a Test Plan?

Solution Preview

In any computer programming language (including Java) comments provide a way for the programmer to explain things that might not be immediately apparent to someone else looking at the code. If, for example, you have just coded a complex mathematical formula that spans thirty lines of code, you would want to explain, preferably in one or two sentences, what the formula is computing and why. That way when someone else is trying to understand what was there, it would make it easier to.

In general, whenever you're starting to code something that starts to seem tricky, you should probably add a comment about it, even if you decide to change it or eliminate it after you're through coding. One way to decide is to ask yourself if you would understand what you'd just done there if you were someone else. Or, if you, yourself, were to return to the code you just wrote three years from now: Would you immediately understand what was going on? If not, a comment there might even save you some work in the future.

Another example might be a series of database calls to retrieve information from several different tables. You might want to write a comment about why the information is being retrieved at that point.

The comments that appear at the beginning of a computer program can be viewed in a similar manner. The best way to decide what comments should be at the top of a program would be to imagine that the program source code (the Java class, in this example) was a much more complicated one, one that spanned thirty lines of code and made mathematical computations. What would you want at the top of that one, especially if you were looking at it for the first time?

Aside from the description, many organizations might also want the name of the author of the program, class, or function. The date it was originally done might be appropriate, too. And if any other people modified it at a later time (to fix a bug or to add an enhancement), their names and the dates they worked on it might also be something a company would want to keep track of. All of this information would be contained in the comments at the top of the program. I think you'll find that even companies that rely on a file management system that forces everyone to check the file out, describing the reason for checking it out, and sign it back in when done, still want their employees to document the changes they made in the source code itself.

According to the Oracle site (http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html at the time of this writing), the Javadoc Documentation Generator will also include all of the comments in a given file, including the ones at the top. The explanation of what the program code is doing, in the comments written by the people actually wrote the code cannot be figured out by the Javadoc program itself. That's why their documentation generator puts them in, too, because the people ...