Comments in functions

Important note: all examples follow aTbRef naming conventions.

---

As Mark Bernstein's book The Tinderbox Way notes: "...the primary audience of a note is almost always our future self." (pg. 33). To wit, comments are notes to our future debugging self.

Action code allows commenting and adding comments to a function is a good idea. The scope and depth of notes is a matter of personal taste, but if making a library of functions for other people, it is a good idea to explain the purpose of the function and the data types of argument and return values.

For example:

	function fAddTax(iPrice){
		// Arguments: iPrice - a number, the starting price
		//
		// make a variable (expected type of Number) and set it to argument #1
		var:number vNum = iPrice;
		// multiply variable by tax rate
		vNum = 1.18 * vNum;
		//return the tax-adjusted price
		return vNum;
	};

To make it easier to see the function code without scrolling, one approach is to put a comment at the start of the function indicating the main detail is at the bottom of the function.

For example, re-using the example above:

	function fAddTax(iPrice){
		// Comments at end

		var:number vNum = iPrice;
		vNum = 1.18 * vNum;
		return vNum;

		// Arguments: iPrice - a number, the starting price
		// make a variable of 'number' type and set it to argument #1 to enforce data type
		// multiply variable by tax rate
		// return the tax-adjusted price
	};

This latter form yields little benefit in a small function like above, but as functions grown in length and number of arguments or return(s) values, coding becomes a big help to future self.

The need for comments really reflects two factors:

• Sharing. If this function will be shared with others, will your logic be self-evident to another user?
• Complexity. Will you—or another user—remember later on the original intent or logic in a large function? What was clear when writing the function may not be so months later if there is next a need to look at the code, e.g. to enhance or correct it, or simply understand how it functions!

---

Next: Nesting functions