Escribir código es muy similar a escribir prosa. Cada persona lo hace un poco diferente, por lo que todos tenemos una voz clara cuando se lee nuestro código. Tenemos diferentes convenciones de nomenclatura y diferentes lógicas de solución de problemas. Todos pensamos que nuestro código tiene sentido, especialmente si funciona, pero alguien más podría no hacerlo. Para remediar esto, todos debemos ser mejores al comentar sobre el código fuente. De esta forma, cualquiera que se acerque al proyecto tendrá un camino claro para entender y mejorar/reparar nuestro código.
Cómo comentar el código: conceptos básicos
Para empezar, asegurémonos de que todos estamos en la misma página cuando se trata de comentarios. En este artículo, cubriremos los comentarios en línea en los propios scripts. Por ejemplo, cosas como esta en un archivo CSS donde el código legible se divide en comentarios que los procesadores ignoran.
/** Body Element Styling **/
body {color:red;}
h1 {size:17px;}
/** Sidebar Widget Styling**/
#email-signup-1 {text-transform:uppercase;}
Cada lenguaje de programación tiene una forma diferente de comentar en el código fuente. PHP y HTML, JavaScript y C # tienen símbolos ligeramente diferentes que comienzan y terminan su código. Si bien también hay prácticas específicas del idioma, hay más de las que hay.
Cubriremos algunos de los diferentes tipos de comentarios que encontrará, sus usos y mejores prácticas (o tal vez solo buenos hábitos que puede incorporar) cuando los use usted mismo.
Las reglas básicas para comentar su código son simples:
- mantenlos cortos
- Manténgalos actualizados
- Úsalos generosamente, pero no en exceso.
Si recuerdas eso, estarás bien.
Hora de hablar de los pesimistas
Analicemos brevemente el código fuente de los pesimistas que comentan. Hay un pequeño grupo de desarrolladores que creen que comentar su código debería ser una ocasión extremadamente rara. El hecho de que cuando necesite comentarios sobre su código fuente significa que su código es débil de alguna manera. Que sus convenciones de nomenclatura, lógica u otra cosa no son tan claras como deberían ser.
Y, francamente, este argumento tiene cierto sentido. Sin embargo, hay muchas circunstancias que son argumento suficiente para incluir documentación en forma de comentarios, por muy bien escrito y distribuido que esté tu código.
El más importante de estos es que no siempre estará trabajando en un proyecto, y no puede garantizar la experiencia que tendrá la siguiente persona. Incluso si escribe un gran código, existe la posibilidad de confusión y ambigüedad.
Documentación del bloque de encabezado
Si observa algunos archivos, el código no se iniciará inmediatamente porque el archivo tiene un encabezado grande que describe su propósito, variables, funciones, métodos, etc. Incluso pueden estar en una caja enorme a su alrededor para llamar la atención.
No es un buen hábito. Porque no tiene sentido. Bueno, en realidad no tiene sentido.
También eche un vistazo al ejemplo anterior: el encabezado del comentario es ridículamente largo. Son muy Rara vez razones para hacerlo. Así que no hagas eso.
Todo lo que pondrías en este archivo debería y así ser incluido en su documentación. No es necesario incluirlo en el comentario. Además, es probable que el usuario final nunca acceda a su código fuente, por lo que el comentario solo será visible para otros desarrolladores (o usuarios de software acérrimos que ya están familiarizados con la documentación).
Además, cada vez que cambia la documentación, hay que cambiarla en este archivo. Es fácil perder un paso y luego su código puede colapsar seriamente.
Cuando los comentarios de encabezado son útiles
Los comentarios del encabezado son útiles en el código fuente para una explicación simple de qué esperar en este archivo. Por ejemplo, este es un script que se envía con un motor de desarrollo de juegos llamado RPG Maker, y el archivo JS base que controla cada escena del juego comienza así:
//=============================================================================
// rpg_scenes.js v1.6.2
//=============================================================================
//=============================================================================
/**
* The Superclass of all scenes within the game.
*
* @class Scene_Base
* @constructor
* @extends Stage
*/
function Scene_Base() {
this.initialize.apply(this, arguments);
}
Scene_Base.prototype = Object.create(Stage.prototype);
Scene_Base.prototype.constructor = Scene_Base;
Además, tenga en cuenta que el número de versión se encuentra en la parte superior. Hazlo. Sin embargo, no incluya una lista exhaustiva de fechas en las que se modificó el archivo y se publicaron nuevas versiones. Se guardan en Git u otro software de control de versiones y deberían estar disponibles para cualquier persona que necesite esta información. El número de versión es suficiente para la mayoría de las personas que verán este archivo.
Documentación en línea
El tipo más común de comentario de código fuente es un comentario en línea. Hay una delgada línea entre ellos entre hacerlo bien, exagerar o ser demasiado frugal. Este es un equilibrio que tienes que aprender con el tiempo, pero hay algunas reglas bastante buenas a considerar.
No haga comentarios línea por línea. El comentario en línea es una cosa. Los comentarios línea por línea hacen que el código sea casi ilegible. Mira abajo:
function sourceCodeComment () { //calls a function
var comment = document.getElementbyID("Code Comment").value; // declares a variable
if (comment != null && comment != '') { //starts an if statement to evaluate if there's a comment
return console.log("Thank you for your comment.") //prints a string to the console
}
Esto es una exageración. Si es necesario, hágalo antes o después de la función. Pero no en todas las líneas. Es intrusivo y generalmente inútil. Comentar antes de una característica (o elemento) es bueno para la organización y la claridad. Más que eso debería estar en la documentación.
Si cree que la documentación es necesaria, algo como esto será suficiente.
//checks to see if there's a comment. If so, returns a thank you message.
function sourceCodeComment () {
var comment = document.getElementbyID("Code Comment").value;
if (comment != null && comment != '') {
return console.log("Thank you for your comment.")
}
Los detractores mencionan que incluso este tipo de comentario es innecesario porque las buenas convenciones para nombrar funciones, variables y métodos harán que el código sea legible. Esto es cierto hasta cierto punto, pero si desea mantener la ambigüedad al mínimo absoluto, un comentario rápido es el camino a seguir.
Puede agregar advertencias en los comentarios al código fuente
A veces la solución obvia al problema no resuelve el problema. En estos casos, los desarrolladores que llegan al proyecto en una etapa posterior de desarrollo pueden mirar el archivo y considerar refactorizarlo. obvio solución. Será una completa pérdida de tiempo.
O tal vez algo más aparecerá en el futuro e intentarán llamar a una función que rompa todo y ponga de rodillas al diseño.
Independientemente, si tiene algo que sabe que no funcionará y sabe que es probable que otras personas lo intenten en el futuro, puede advertirles al respecto.
// Don't bother trying to use goodCodeComment() here.
// It breaks bestPractices() despite seeming like the best option.
// We went with simplyOkayCodeComment() instead.
function simpleOkayCodeComment() {
//some kind of code goes here
}
¿También notaste lo que hicimos en este ejemplo? No solo dimos una advertencia a los futuros desarrolladores, sino que también incluimos un comentario de marcador de posición en el medio de la función. Dado que los comentarios en el código fuente se ignoran, puede usarlos para almacenar texto de marcador de posición en un archivo (algo así como anotaciones para que usted mismo vuelva allí, o como un ejemplo para alguien como explicación).
no seas un idiota
He visto esto antes, especialmente en proyectos de código abierto que no estaban muy bien moderados. Alguien encontrará un fragmento menos que estelar y utilizará un comentario para insultar al autor.
//This function looks like it was written by a third grader. //It shouldn't work, but it does somehow. I don't want //to fix it because I want you all to see how bad it is.
O tal vez arreglen el código, pero lo incluirán, solo comentado, para que puedan mostrar su código mientras se burlan del autor anterior.
//The old code was so bad, I just had to leave it here for you to see.
//I fixed it. My code is below. But look at this.
// function theMatrix() {
// var neo = maybeTheOne.data + theOracle.data
// if theOne() !== neo
// return console.log("you got the gift, but it looks like you're waiting for something")
// }
Solo asegúrate de no hacerlo nunca. Incluso si piensas que eres divertido o que te hace ver bien, no lo es y no lo es.
El uso real de comentar el código es tenerlo a mano cuando se intenta otra cosa. O dar un ejemplo de lo que no funcionó antes, para que nadie lo vuelva a intentar sin éxito.
Comentarios de código fuente para WordPress
En general, WordPress funciona en cuatro idiomas diferentes. HTML, CSS, PHP y JavaScript. Es imperativo que se asegure de utilizar los caracteres correctos en sus comentarios.
Para HTML:
<!-- comments go here and can be single or on multiple lines --></em>
En CSS:
/* Any number of lines will be a comment until the comment is closed */
Tanto PHP como JavaScript tienen los mismos métodos para crear comentarios de una o varias líneas:
<?php function(); // a single line comment is like this ?>
o
<?php /* unlike above, you can carriage return and no matter how many lines you use, the comment won't stop until closed */
Solicitud
Si trabaja en las trincheras todos los días, escribiendo código y enviándolo a GitHub, su organización puede tener una guía sobre el estilo de comentarios que desea seguir. Sin embargo, si no lo hacen, o si está solo, tener estas cosas en mente no solo facilitará su trabajo en el futuro, sino que también ayudará a cualquiera que venga después de usted.
¿Qué consejos y trucos tienes para aprovechar al máximo los comentarios sobre tu código?
Artículo con una imagen de Skillup / shutterstock.com
