IT Knowledge: best practices

Showing posts with label best practices. Show all posts

Friday, October 9, 2020

Block Comment Templates with Examples

(McCann)
Last Updated: August 2015

Here are the block commenting templates to use for internal and external block comments in your programs.

Toward the bottom of this document are two examples of internal block comments, along with some commentary about their quality. Hopefully they will help you understand what makes an internal block comment a good one. If you're taking a lower-level programming class, see the example code for that class for additional documentation examples.

Why Block Comments?

Consider the Java API documentation. Each class starts with a (usually lengthy) description of the purpose of the class and how it fits into the Java class hierarchy. That's a block comment. Each method has a similar block of documentation associated with it. Without these comments, the programmer would have a hard time using the class or its method effectively. You should do the same for your code. Java's API is documented using a commenting style that is compatible with a tool called Javadoc. That's great for documentation that lots of people will be referencing, but not so good for commenting one-off student programs. So, we don't use Javadoc, but we do require that you write complete, well-structured block comments for your classes and methods.

In addition, you need to place a block comment ahead of the class containing your main() method. We call this an `external' block comment because it replaces the external documentation that would normally accompany a complete program.

Using the Templates

To make entering block comments as painless as possible, we supply outlines of each type of block comment. The idea behind having these templates is that you can use your editor to add a template to your code and then just type in the appropriate information for each section in the template. This will help because it saves you some typing and makes sure you don't leave out an entire section of information.

To include these in your source code file on a lab machine, edit your source code file, position your cursor on a blank line at the point in your code where you wish to place a template, and then use your editor's file-reading command to read in the template you want. For example, in vi the command to include a file is :r filename. So, to read in the internal.txt template, you'd give the vi command of:

:r /cs/www/people/mccann/templates/internal.txt

Then all you need to do is fill in the template with the details of the method you are trying to document.

Another option is to copy the templates to your directory, delete the explanation text from your copies, and add common information to them that you'd always enter (such as your name in the external block comment template). Then you can add these "pre-editted" blocks to your program and speed up the commenting process even further.

Java Templates:

internal.txt and int.txt:

An internal block comment belongs immediately ahead of each method of your program, with two exceptions. First, main() is assumed to be covered by the external block comment. Second, if your class has a group of getters and setters, you may cover the entire group with one block comment. The file internal.txt has exactly what you see below. int.txt is just the box and section names; it's easier to import into your code, because you don't have to delete the explanations before entering your own text.

       /*---------------------------------------------------------------------
        |  Method [Method Name]
        |
        |  Purpose:  [Explain what this method does to support the correct
        |      operation of its class, and how it does it.]
        |
        |  Pre-condition:  [Any non-obvious conditions that must exist
        |      or be true before we can expect this method to function
        |      correctly.]
        |
        |  Post-condition: [What we can expect to exist or be true after
        |      this method has executed under the pre-condition(s).]
        |
        |  Parameters:
        |      parameter_name -- [Explanation of the purpose of this
        |          parameter to the method.  Write one explanation for each
        |          formal parameter of this method.]
        |
        |  Returns:  [If this method sends back a value via the return
        |      mechanism, describe the purpose of that value here, otherwise
        |      state 'None.']
        *-------------------------------------------------------------------*/

class.txt and cl.txt:

Each class you write, except the class containing main(), must have a block comment of this form ahead of it.

/*+----------------------------------------------------------------------
 ||
 ||  Class [Class Name] 
 ||
 ||         Author:  [Your Name]
 ||
 ||        Purpose:  [A description of why this class exists.  For what
 ||                   reason was it written?  Which jobs does it perform?]
 ||
 ||  Inherits From:  [If this class is a subclass of another, name it.
 ||                   If not, just say "None."]
 ||
 ||     Interfaces:  [If any predefined interfaces are implemented by
 ||                   this class, name them.  If not, ... well, you know.]
 ||
 |+-----------------------------------------------------------------------
 ||
 ||      Constants:  [Name all public class constants, and provide a very
 ||                   brief (but useful!) description of each.]
 ||
 |+-----------------------------------------------------------------------
 ||
 ||   Constructors:  [List the names and arguments of all defined
 ||                   constructors.]
 ||
 ||  Class Methods:  [List the names, arguments, and return types of all
 ||                   public class methods.]
 ||
 ||  Inst. Methods:  [List the names, arguments, and return types of all
 ||                   public instance methods.]
 ||
 ++-----------------------------------------------------------------------*/

external.txt or ext.txt:

At the top of the file containing your program's main() method, place an `external' block comment containing the following content.

/*=============================================================================
 |   Assignment:  Program #[n]:  [Assignment Title]
 |       Author:  [Your Name (Your E-mail Address)]
 |       Grader:  [Your TA or Section Leader's name]
 |
 |       Course:  [Course Number]
 |   Instructor:  L. McCann
 |     Due Date:  [Due Date and Time]
 |
 |  Description:  [Describe the program's goal, IN DETAIL.]
 |
 |     Language:  [Programming language and version used.]
 | Ex. Packages:  [List names and sources of all external packages
 |                required by this program.]
 |                
 | Deficiencies:  [If you know of any problems with the code, provide
 |                details here, otherwise clearly state that you know
 |                of no unsatisfied requirements and no logic errors.]
 *===========================================================================*/

Examples of Good and Bad Block Comments

Contrary to popular student opinion, I don't require all of the commenting as an annoyance to you. It has been estimated that about 70% of programming effort is put into the maintenance of old code, and the rest into the development of new code. It is safe to assume that, should you do some programming in your career, you will be needing to modify someone else's code to fix an old bug or to extend the code's functionality. Commenting exists to help those unfortunate programmers who have to look at the code months or years after it was written. When you write comments for your code, keep that in mind and include useful information rather than details that are plainly obvious. The future programmers will know the language; you don't need to explain what "i ≤ j" means! Instead, explain why it's important that this condition be checked at this point in the code. Do you understand the difference?

As an example, let's imagine that you're going to write a subprogram that searches a list of earthquake intensities to find the most powerful quake. I am not going to show any code for this routine; this is intentional! The internal block comment is meant to give an overview of the construction and operation of the routine. If the reader wants more detail, he or she can move on to read the code, which will have its own comments about the code itself.

A Bad Internal Block Comment

Here's our first example of a block comment for our earthquake intensity search routine. This is not an actual example from a student program, but it does (I hope!) capture most of the mistakes students make when they wait until the last minute to write a comment:

        /*---------------------------------------------------------------------
         |  Method FIND_BIGGEST_QUAKE
         |
         |  Purpose:  Find the biggest earthquake.
         |
         |  Pre-condition: Earthquakes are available.
         |
         |  Post-condition: We found the biggest one.
         |
         |  Parameters:
	 |	quakeList -- the quakes
	 |	size      -- size of the list
         |
         |  Returns:  The biggest quake
         *-------------------------------------------------------------------*/

What's wrong with this comment? Most everything! Where to start?

The description of the purpose of the function is useless; we could have figured as much from the name of the method alone! What we really need to know is exactly what job this method performs. For instance, it would be really nice to know what "biggest" means in this context. Largest measure on the Richter Scale? Most damage caused?
Pre- and Post-conditions are supposed to tell us what needs to be true before (Pre-) and after (Post-) this method executes. They need to be clear and unambiguous, not wishy-washy. These are wishy-washy.
The structure of the quake_list parameter is not even mentioned.
How is the list size measured? By number of items or by index position of the last item?
Exactly what about the biggest earthquake is being returned? Its position in the list? Its measured size? The entire entry from the list?

Again, the point is that anyone reading this comment will have learned almost nothing about this method. You are forcing the reader to wade through the code to learn anything of substance.

A Good Internal Block Comment

Compare the first attempt to this one:

        /*---------------------------------------------------------------------
         |  Method FIND_BIGGEST_QUAKE
         |
         |  Purpose:  Identify the earthquake from the list of earthquake
	 |	intensities (quakeList) that has the largest magnitude.
	 |	It is assumed that the given list of quake intensities is
	 |	an array-based list of unordered Richter Scale 
	 |	magnitudes; this function performs a simple sequential
	 |	search through the array to locate the position of the
	 |	largest magnitude (the largest value) in the list.
         |
         |  Pre-condition: quakeList holds 1 or more intensities; the
         |      intensities are in no particular order; numEntries holds
         |      the exact number of entries currently in the list.
         |
         |  Post-condition: quakeList and numEntries are unchanged; the 
         |      list position of the entry with the largest magnitude has 
         |      been identified; the position is within the boundaries
         |      of the array.
         |
         |  Parameters:
	 |	quakeList -- the array of earthquake magnitudes.  This
	 |		is an array of real numbers; the first magnitude
	 |		is assumed to be at index 0.
	 |	numEntries -- the quantity of magnitudes in quakeList.
         |
         |  Returns:  The index (position) of the largest earthquake
	 |	magnitude in the quakeList array.
         *-------------------------------------------------------------------*/

Obviously, this comment includes many more details. A programmer reading this comment will have a good understanding of the operation of the method and this knowledge will make reading the code easier, should the programmer find that to be necessary. (It's very possible that all they needed to know about this method was found in the comment.)

Note that the description of the subprogram includes the algorithm(s) used to carry out the work of the routine, but includes no details about the implementation of the algorithm(s). Readers who want that level of detail will need to read the code.

Also note that this comment could have been (nay, should have been) written before the subprogram was written! This is not unusual at all; when you write your code, you should be following a detailed outline that you developed first. Your block comments can be written based on your outline of the operation of the routine. In other words, there is no excuse for you to wait until the last minute to do your commenting!

source : http://u.arizona.edu/~mccann/styletemplates.html

Comment : JavaScript Documentation Standards

What Should Be Documented What Should Be Documented

JavaScript documentation in WordPress takes the form of either formatted blocks of documentation or inline comments.

The following is a list of what should be documented in WordPress JavaScript files:

Functions and class methods
Objects
Closures
Object properties
Requires
Events
File headers

Tag	Description
@abstract	This method can be implemented (or overridden) by the inheritor.
@access	Specify the access level of this member (private, public, or protected).
@alias	Treat a member as if it had a different name.
@augments	This class inherits from a parent class.
@author	Identify the author of an item.
@borrows	This object uses something from another object.
@callback	Document a callback function.
@class	This function is a class constructor.
@classdesc	Use the following text to describe the entire class.
@constant	Document an object as a constant.
@constructs	This function member will be the constructor for the previous class.
@copyright	Document some copyright information.
@default	Document the default value.
@deprecated	Document that this is no longer the preferred way.
@description	Describe a symbol.
@enum	Document a collection of related properties.
@event	Document an event.
@example	Provide an example of how to use a documented item.
@exports	Identify the member that is exported by a JavaScript module.
@external	Document an external class/namespace/module.
@file	Describe a file.
@fires	Describe the events this method may fire.
@function	Describe a function or method.
@global	Document a global object.
@ignore	[todo] Remove this from the final output.
@inner	Document an inner object.
@instance	Document an instance member.
@kind	What kind of symbol is this?
@lends	Document properties on an object literal as if they belonged to a symbol with a given name.
@license	[todo] Document the software license that applies to this code.
@link	Inline tag – create a link.
@member	Document a member.
@memberof	This symbol belongs to a parent symbol.
@mixes	This object mixes in all the members from another object.
@mixin	Document a mixin object.
@module	Document a JavaScript module.
@name	Document the name of an object.
@namespace	Document a namespace object.
@param	Document the parameter to a function.
@private	This symbol is meant to be private.
@property	Document a property of an object.
@protected	This member is meant to be protected.
@public	This symbol is meant to be public.
@readonly	This symbol is meant to be read-only.
@requires	This file requires a JavaScript module.
@return	Document the return value of a function.
@see	Refer to some other documentation for more information.
@since	Documents the version at which the function was added, or when significant changes are made.
@static	Document a static member.
@this	What does the ‘this’ keyword refer to here?
@throws	Describe what errors could be thrown.
@todo	Document tasks to be completed.
@tutorial	Insert a link to an included tutorial file.
@type	Document the type of an object.
@typedef	Document a custom type.
@variation	Distinguish different objects with the same name.
@version	Documents the version number of an item.
@yield	Document the yielded values of a generator function.

Tag	Why it’s not supported
@summary	Should not be used. See the example of how to separate a summary from the full description.
@virtual	An unsupported synonym. Use @abstract instead.
@extends	An unsupported synonym. Use @augments instead.
@constructor	An unsupported synonym. Use @class instead.
@const	An unsupported synonym. Use @constant instead.
@defaultvalue	An unsupported synonym. Use @default instead.
@desc	An unsupported synonym. Use @description instead.
@host	An unsupported synonym. Use @external instead.
@fileoverview	An unsupported synonym. Use @file instead.
@overview	An unsupported synonym. Use @file instead.
@emits	An unsupported synonym. Use @fires instead.
@func	An unsupported synonym. Use @function instead.
@method	An unsupported synonym. Use @function instead.
@var	An unsupported synonym. Use @member instead.
@emits	An unsupported synonym. Use @fires instead.
@arg	An unsupported synonym. Use @param instead.
@argument	An unsupported synonym. Use @param instead.
@prop	An unsupported synonym. Use @property instead.
@returns	An unsupported synonym. Use @return instead.
@exception	An unsupported synonym. Use @throws instead.

Friday, October 9, 2020

Block Comment Templates with Examples

Comment : JavaScript Documentation Standards

What Should Be Documented #What Should Be Documented

Documenting Tips #Documenting Tips

Language #Language

Grammar #Grammar

Formatting Guidelines #Formatting Guidelines

Line wrapping #Line wrapping

Aligning comments #Aligning comments

Functions #Functions

Backbone classes #Backbone classes

Local functions #Local functions

Local ancestors #Local ancestors

Class members #Class members

Namespaces #Namespaces

Inline Comments #Inline Comments

Single line comments #Single line comments

Multi-line comments #Multi-line comments

File Headers #File Headers

Supported JSDoc Tags #Supported JSDoc Tags

Unsupported JSDoc Tags #Unsupported JSDoc Tags

What Should Be Documented What Should Be Documented

Documenting Tips Documenting Tips

Language Language

Grammar Grammar

Formatting Guidelines Formatting Guidelines

Line wrapping Line wrapping

Aligning comments Aligning comments

Functions Functions

Backbone classes Backbone classes

Local functions Local functions

Local ancestors Local ancestors

Class members Class members

Namespaces Namespaces

Inline Comments Inline Comments

Single line comments Single line comments

Multi-line comments Multi-line comments

File Headers File Headers

Supported JSDoc Tags Supported JSDoc Tags

Unsupported JSDoc Tags Unsupported JSDoc Tags