Una de las mejores piezas que he encontrado de código fuente claro y conciso es la fuente jQuery. Si le gusta Javascript o no, es un gran caso contra los defensores de "el código es la documentación".
Hay muchos comentarios pero no es una obra de arte ascii y puede ver un razonamiento claro: los comentarios le hacen saber exactamente lo que se intenta lograr.
Un ejemplo (full source):
(function(){
var
// Will speed up references to window, and allows munging its name.
window = this,
// Will speed up references to undefined, and allows munging its name.
undefined,
// Map over jQuery in case of overwrite
_jQuery = window.jQuery,
// Map over the $ in case of overwrite
_$ = window.$,
jQuery = window.jQuery = window.$ = function(selector, context) {
// The jQuery object is actually just the init constructor 'enhanced'
return new jQuery.fn.init(selector, context);
},
// A simple way to check for HTML strings or ID strings
// (both of which we optimize for)
quickExpr = /^[^<]*(<(.|\s)+>)[^>]*$|^#([\w-]+)$/,
// Is it a simple selector
isSimple = /^.[^:#\[\.,]*$/;
jQuery.fn = jQuery.prototype = {
init: function(selector, context) {
// Make sure that a selection was provided
selector = selector || document;
// Handle $(DOMElement)
if (selector.nodeType) {
this[0] = selector;
this.length = 1;
this.context = selector;
return this;
}
// Handle HTML strings
if (typeof selector === "string") {
// Are we dealing with HTML string or an ID?
var match = quickExpr.exec(selector);
// Verify a match, and that no context was specified for #id
if (match && (match[1] || !context)) {
// HANDLE: $(html) -> $(array)
if (match[1])
selector = jQuery.clean([ match[1] ], context);
// HANDLE: $("#id")
else {
var elem = document.getElementById(match[3]);
// Handle the case where IE and Opera return items
// by name instead of ID
if (elem && elem.id != match[3])
return jQuery().find(selector);
...
La mayoría de los comentarios podrían haberse evitado. "el código es la documentación" no se trata de ensuciar el código con comentarios, realmente. Martin Fowler me iluminó cuando leí que los comentarios son olores de códigos. – rpattabi
Me gustan la mayoría de esos comentarios. Mantienen mi política de comentar no decir QUÉ estoy haciendo sino POR QUÉ. –
@sebstian exactamente, sin los comentarios no tendrías idea de por qué 'window = this' se está utilizando. @ ragu.pattabi ¿te refieres a esto: http://martinfowler.com/bliki/CodeAsDocumentation.html? Él no menciona nada sobre los comentarios, solo que el código claro es auto-documentado. –