What does this method signature tell you?

jQuery.extend = jQuery.fn.extend = function() {
 ...
}

Above piece of code is taken from jQuery. Here is the documentation for extend method .

How much to document a code is a tricky subject. And there is no clear answer. In episode 80 of stackoverflow podcast Joel and Jeff discussed this issue.

Developers do not read much documentation. However that does not mean that there is no room for documentation. Some suggest to look at unit tests to understand code. Unit tests help to find out if I broke anything. But to understand what the code does I still need to look at code. Unit tests know the final result. Code will tell you what is the algorithm to get to final result.

My take is that documentation is not a substitute for poor code quality. Write the very best code you can and then write some documentation. Also what language you use matters a lot. In Java and .NET and other statically typed languages method signature tells you a lot. In a dynamically typed language like JavaScript signatures are not that helpful.

If you are curious here is the full implementation of the extend method mentioned above.

jQuery.extend = jQuery.fn.extend = function() {
	// copy reference to target object
	var target = arguments[0] || {}, i = 1, length = arguments.length, deep = false, options, name, src, copy;

	// Handle a deep copy situation
	if ( typeof target === "boolean" ) {
		deep = target;
		target = arguments[1] || {};
		// skip the boolean and the target
		i = 2;
	}

	// Handle case when target is a string or something (possible in deep copy)
	if ( typeof target !== "object" && !jQuery.isFunction(target) ) {
		target = {};
	}

	// extend jQuery itself if only one argument is passed
	if ( length === i ) {
		target = this;
		--i;
	}

	for ( ; i < length; i++ ) {
		// Only deal with non-null/undefined values
		if ( (options = arguments[ i ]) != null ) {
			// Extend the base object
			for ( name in options ) {
				src = target[ name ];
				copy = options[ name ];

				// Prevent never-ending loop
				if ( target === copy ) {
					continue;
				}

				// Recurse if we're merging object literal values or arrays
				if ( deep && copy && ( jQuery.isPlainObject(copy) || jQuery.isArray(copy) ) ) {
					var clone = src && ( jQuery.isPlainObject(src) || jQuery.isArray(src) ) ? src
						: jQuery.isArray(copy) ? [] : {};

					// Never move original objects, clone them
					target[ name ] = jQuery.extend( deep, clone, copy );

				// Don't bring in undefined values
				} else if ( copy !== undefined ) {
					target[ name ] = copy;
				}
			}
		}
	}

	// Return the modified object
	return target;
};