I wish to add helpful comments without being too verbose. Before answering imagine given Javascript functions buried somewhere inside hundreds or thousands of lines source code. Also notice that in the comments I gave function parameters a little bit more meaning by better describing their usage instead of using actual names of parameters. I do this to better guide the user (programmer) who may at a later date need to refactor or modify the script.
var ctx = getCanvas();// getCanvas(width, height)
grid(ctx);// grid(context, element size, line width, line color)
function getCanvas(width = 200, height = 150) {
// code to run
}
function grid(ctx, elSize = 10, width = .3, color = 'green') {
// code to run
}
Well, it's always good to have your code properly commented.
Add a standard/descriptive comments before the start of the function instead of lines of comments.
There are many ways to add a comments in JavaScript; here is my recommendation / best practices.
Using // is better than /* */ because then you can use the latter to take out an entire block containing other comments. However, if you want to use an automatic documentation generation tool, you must use comments similar to JavaDoc style.
This is an example that would work with YUI DOC (best one) http://developer.yahoo.com/yui/yuidoc/#start
/**
* This is a description
* @namespace My.Namespace
* @method myMethodName
* @param {String} str - some string
* @param {Object} obj - some object
* @param {requestCallback} callback - The callback that handles the response.
* @return {bool} some bool
*/
function SampleFunction (str, obj, callback) {
var isTrue = callback(str, obj); // do some process and returns true/false.
return isTrue ;
}
Other params examples: http://usejsdoc.org/tags-param.html