Cómo comentar su código como un profesional: mejores prácticas y buenos hábitos

Escribir código es muy parecido a escribir prosa. Cada persona lo hace de manera un poco diferente, y por eso, todos tenemos una voz distinta cuando se lee nuestro código. Tenemos diferentes convenciones de nomenclatura y diferentes lógicas de resolución de problemas. Todos pensamos que nuestro código tiene sentido, especialmente si funciona, pero es posible que alguien más no. Para combatir esto, todos necesitamos mejorar en los comentarios de código fuente. De esa manera, quien venga al lado del proyecto tendrá un camino claro para comprender y mejorar / corregir 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 con respecto a los comentarios. En este artículo, discutiremos los comentarios en línea dentro de los propios scripts. Cosas como esta en un archivo CSS, por ejemplo, donde el código legible está dividido por comentarios que son ignorados por los procesadores.

/** 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 y JavaScript y C # tienen símbolos ligeramente diferentes que comienzan y terminan el código. Si bien también existen algunas prácticas específicas del idioma, se comparten más de las que no.

Discutiremos algunos de los diferentes tipos de comentarios con los que se encontrará, sus usos y mejores prácticas (o tal vez solo buenos hábitos para adquirir) cuando los use usted mismo.

Los principios básicos para comentar su código son simples:

• Hazlos breves
• Mantenlos relevantes
• Úselos generosamente, pero no en exceso

Si puede tenerlos en cuenta, lo estará haciendo bastante bien.

Un momento para discutir sobre los detractores

Muy brevemente, vamos a tocar el código fuente que comenta a los detractores. Hay un subconjunto no pequeño de desarrolladores que creen que comentar su código debería ser una ocasión excepcionalmente rara. Que cuando necesite comentarios en el código fuente, eso es una indicación de que su código es débil de alguna manera. Que sus convenciones de nomenclatura, lógica u otra cosa no es tan transparente como debería ser.

Y, para ser justos, este argumento tiene cierto sentido. Sin embargo, existen varias circunstancias que hacen que un argumento sea más que suficiente para incluir documentación en forma de comentarios, independientemente de lo bien escrito y factorizado que esté su código.

Los principales son que no siempre serás tú quien trabaje en el proyecto y no puedes garantizar la experiencia que tendrá la próxima persona. Incluso si escribe un buen código, existe la posibilidad de confusión y ambigüedad.

Documentación del bloque de encabezado

Si busca en algunos archivos, el código no comienza de inmediato porque hay un encabezado grande en el archivo que describe cuál es su propósito, las variables, funciones, métodos, etc. Incluso podrían estar en una caja gigante a su alrededor para llamar su atención.

Este no es un buen hábito para adquirir. Porque no tiene sentido. Bueno, en realidad no tiene sentido.

Además, mire el ejemplo anterior: el encabezado del comentario es absurdamente largo. Hay muy pocas veces razones para hacerlo. Así que no lo hagas.

Cualquier cosa que ponga en ese archivo debe incluirse en su documentación de todos modos. Tenerlo en un comentario es redundante. Además, es probable que el usuario final nunca acceda a su código fuente, por lo que el comentario solo lo verán otros desarrolladores (o usuarios expertos del software que ya conocen la documentación).

Además, cada vez que cambia la documentación, debe cambiarla en ese archivo. Es fácil perder un paso, y luego su código base puede ensuciarse seriamente.

Cuando los comentarios del encabezado son útiles

Los comentarios de encabezado son útiles en el código fuente para explicaciones simples de qué esperar en ese archivo. Por ejemplo, este es un script que viene con un motor de desarrollo de juegos llamado RPG Maker, y el archivo JS central 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 aparece en la parte superior. Hacer esto. Sin embargo, no proporcione una lista completa de las fechas en las que se modificó el archivo y se publicaron nuevas versiones. Eso se registra en Git u otro software de control de versiones, y debería estar disponible para cualquier persona que necesite esa información. El número de versión es suficiente para la mayoría de las personas que verían este archivo.

Documentación en línea

El tipo más común de comentario de código fuente es el comentario en línea. Hay una línea muy fina entre hacerlo bien, ir por la borda o ser demasiado parco con ellos. Es un equilibrio que debe aprender con el tiempo, pero hay algunas reglas generales bastante buenas a considerar.

No hagas comentarios línea por línea. Los comentarios en línea son una cosa. Los comentarios línea por línea hacen que el código parezca casi ilegible. Vea 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
}

Eso es exagerado. Si es necesario, hágalo antes o después de la función. Pero no en cada línea. Es molesto y generalmente inútil. Un comentario antes de la función (o elemento) es bueno para la organización y la claridad. Más que eso debería ir en la documentación.

Si cree que es necesario documentar, 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 mencionarán que incluso este tipo de comentario es redundante porque las buenas convenciones de nomenclatura para sus funciones, variables y métodos harán que el código sea legible. Eso 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.

Está bien poner advertencias en los comentarios del código fuente

A veces, la solución obvia a un problema no resuelve realmente el problema. En estos casos, los desarrolladores que llegan a un proyecto más adelante en el desarrollo pueden mirar un archivo y considerar refactorizarlo tomando esa solución obvia . Hacerlo será una completa pérdida de tiempo.

O tal vez surja algo más en el futuro, e intentan llamar a una función que rompe todo y pone de rodillas el proyecto.

Independientemente, si tienes algo que sabes con certeza que no funcionará y que sabes que es probable que otras personas lo intenten en el futuro, está bien 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
}

Además, ¿notaste lo que hicimos en ese ejemplo? No solo dimos la advertencia a futuros desarrolladores, sino que incluimos un comentario de marcador de posición en medio de una función. Debido a que se ignoran los comentarios del código fuente, puede usarlos para mantener el texto del marcador de posición en el archivo (como una anotación para usted para regresar allí, o como un ejemplo para alguien como explicación).

No seas un idiota

He visto que esto sucedía antes, especialmente en proyectos de código abierto que no estaban muy bien moderados. Alguien encontrará un fragmento de código menos que estelar y usará un comentario para desprestigiar 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 arreglan el código, pero incluyen el código, simplemente comentado, para que puedan mostrar su código, mientras que al mismo tiempo 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 hacer nunca esto. Incluso si crees que estás siendo gracioso o que te hace lucir bien, no lo es y no lo es.

El uso real de comentar el código es que lo tengas a mano mientras intentas algo más. O para dar un ejemplo de lo que no funcionó antes para que nadie lo vuelva a intentar en vano.

Comentarios del código fuente para WordPress

En general, WordPress se ejecuta en cuatro idiomas diferentes. HTML, CSS, PHP y JavaScript. Es imperativo asegurarse de utilizar los caracteres correctos para los 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 hacer 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 */

Conclusión

Si estás en las trincheras día tras día, escribiendo código y presionando a GitHub, tu organización puede tener una guía de estilo para los comentarios que quieren que sigas. Sin embargo, si no lo hacen, o si está solo, tener esto en cuenta no solo facilitará su trabajo en el futuro, sino que también ayudará a cualquiera que venga después de usted.

¿Cuáles son sus consejos y trucos para aprovechar al máximo los comentarios de su código?

Imagen destacada del artículo de Skillup / shutterstock.com