Comments in functions

Important note: all examples follow aTbRef naming conventions.

As Mark Bernstein's book The Tinderbox Way notes (p.33): "...the primary audience of a note is almost always our future self.". Thus, out comments are notes to our future debugging self (unless constructing demos/examples for others).

Action code allows commenting and adding comments to a function is a good idea. Comments may be placed within function code or outside it (e.g. before or after the functions/code. As the Tinderbox action code parser ignores comments their position, and the scope and depth of notes is a matter of personal taste. However, if making a library of functions for other people, it is a good idea to explain:

the purpose of the function
the purpose and (intended) data types of the argument(s)
the return value(s).
the logic if multiple return statements are used within conditional code

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

See also—notes linking to here: