Tinderbox v9 Icon

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:


Next: Nesting functions