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

La escritura del código se asemeja a la escritura de la prosa. Cada persona lo hace un poco diferente y, debido a esto, todos tenemos una voz distinta cuando se lee nuestro código. Tenemos diferentes convenciones de citas y diferentes lógicas de resolución de problemas. Todos creemos que nuestro código tiene sentido, especialmente si funciona, pero alguien más no podría. Para combatir esto, todos necesitamos mejorar nuestros comentarios sobre el código fuente. De esta manera, cualquiera que se acerque al proyecto tendrá una manera clara de comprender y mejorar / remediar nuestro código. Cómo comentar el código: los elementos básicos para el principio, asegurémonos de que todos estemos en la misma página sobre cuáles son los comentarios. En este artículo, discutiremos los comentarios en línea dentro de las Escrituras. Cosas de este tipo en un archivo CSS, por ejemplo, donde el código legible se divide por los comentarios que son ignorados por los procesadores.
/** Estilización de elementos corporales **/
Cuerpo {color: rojo;}
H1 {tamaño: 17px;}
/** Estilización de widgets de barra lateral **/
#Correo electrónico-firmante-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 todos símbolos ligeramente diferentes que comienzan y terminan el código. Aunque hay algunas prácticas específicas del lenguaje, hay más compartir que no. Discutiremos los diferentes tipos de comentarios que cumplirá, sus usos y mejores prácticas (o tal vez solo buenos hábitos para ingresar) al usarlos usted mismo.
Los principios básicos de su comentario de código son simples:
Hazlos cortos
Manténgalos relevantes
Úselos libremente pero no en exceso
Si puede tenerlos en cuenta, irá bien. Un momento para discutir los detractores muy brevemente, para llegar al código fuente que comenta a Nayayers. Hay un pequeño subconjunto de desarrolladores que creen que su comentario de código debería ser una ocasión excepcional. Que cuando necesita comentarios sobre el código fuente, esta es una indicación de que su código es débil en cierto modo. Que el nombre de las convenciones, la lógica o algo más no son tan transparentes como deberían. Y, para ser correctos, este argumento tiene un cierto significado. Sin embargo, hay una serie de circunstancias que hacen un argumento más que suficiente para incluir la documentación en forma de comentarios, no, él trabaja en el proyecto y no puede garantizar cuán experimentado será el próximo hombre. Incluso si escribe un código excelente, hay posibilidades de confusión y ambigüedad. Documentación del bloque de encabezado Si mira 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, variables, funciones, métodos, etc. Incluso podría estar en una gran caja a su alrededor atraer su atención.
Este no es un buen hábito para entrar. Porque es un poco inútil. Bueno, en realidad es inútil.
Además, mire el ejemplo anterior: el encabezado de comentarios es absurdamente largo. Hay razones muy raras para hacer esto. Entonces no. Cualquier cosa que ingrese en ese archivo debe ingresarse de todos modos en su documentación para tenerlo en un comentario es redundante. Además, el usuario final nunca ingresará su código fuente, por lo que el comentario solo será visto por otros desarrolladores (o por los usuarios importantes del software que ya conocen la documentación). Además, cada vez que se cambia la documentación. debe cambiarlo en ese archivo. Es fácil perder un paso y luego la base del código puede verse severamente afectada. Cuando los comentarios para el encabezado son útiles, los comentarios del encabezado son útiles en el código fuente para explicaciones simples de qué esperar en ese archivo. Por ejemplo, este es un guión que viene con un motor de desarrollo de juegos llamado RPG Maker, y el archivo JS básico que controla cada escena del juego comienza de la siguiente manera: // ============= = = ============================================ ======= =======

// rpg_scenes.js v1.6.2
// ================================================= =======================
// ================================================= =======================
/**
* La superclase de todas las escenas dentro del juego.
*
* @class escena_base
* @constructor
* @Extendes Etapa
*/
Función escena_base () {
this.initialize.apply (esto, argumentos);
}
Escena_base.prototype = objeto.create (stage.prototype);
Escena_base.prototype.constructor = escena_base;
Además, tenga en cuenta que el número de versión se enumera en la parte superior. Hacer esto. Sin embargo, no proporcione una lista completa de datos a los que el archivo ha sido modificado y publicado nuevas versiones. Esto se registra en Git u otro software de control de versiones y debe estar disponible para cualquier persona que necesite esta información. El número de versión es suficiente para la mayoría de las personas que habrían olvidado este archivo. El tipo más común de comentario del código fuente está en línea es el comentario de la línea. Hay una delgada línea entre ellos que hacen el bien, suben a bordo o son demasiado repuestos con ellos. Es un equilibrio que debe aprender solo con el tiempo, pero hay algunas reglas generales a considerar. No hagas comentarios de fila. El comentario en línea es una cosa. El comentario de la fila con una fila hace que el código parezca casi ilegible. Vea abajo:
Function SourCeCodeComment () {// llama a una función
Var comentar = document.getElementById (“comentario de código”). Valor; // declara una variable
if (comment! = null && comment! = ”) {// inicia una instrucción if a evaluado si hay un comentario

return console.log (“Gracias por su comentario”) // Imprime una cadena en la consola
}
Eso es excesivo. Si necesita hacerlo antes o después del cargo. Pero no en cada línea. Es invasor y generalmente inútil. Un comentario antes de la función (o elemento) es bueno para la organización y la claridad. Además, deben ingresar la documentación.
Si cree que es necesario documentarse, esto será suficiente. // verifica si hay un comentario. Si es así, devuelva un mensaje de agradecimiento.
Function SourCeCodeComment () {
VAR comment = document.getElementById (“comentario de código”). Valor; if (comentario! = Null && comment! = ”) {
regresar console.log (“Gracias por su comentario”)
}
Los detractores mencionarán que incluso este tipo de comentario es redundante, porque las convenciones de buen nombre para sus funciones, variables y métodos hará el código. Esto es cierto en un punto, pero si desea mantener la ambigüedad al mínimo absoluto, un comentario rápido es el camino a seguir.
Está bien ingresar advertencias en los comentarios sobre el código fuente a veces, la solución obvia de un problema en realidad no resuelve el problema. En estos casos, los desarrolladores que llegan a un proyecto más tarde se desarrollan pueden mirar un archivo y podrían considerar su restauración, teniendo en cuenta esta solución obvia. Hacer esto será una completa pérdida de tiempo. O tal vez aparecerá algo más en el futuro e intente nombrar una función que rompa todo y ponga el proyecto de rodillas. Ya sea que tenga algo que sabe, de hecho, no funcionará y sabe que otras personas probablemente intentarán en el futuro, es bueno advertirles al respecto.
// no intenta usar GoodCodeComment () aquí.
// Romper BestPractices () Split parece la mejor opción.
// Fuimos con SimplyokayCodeComment () Intead.
function simpleokayCodeComment () {
// algún tipo de código va aquí
}
¿También notaste lo que hice en este ejemplo? No solo advertí a los futuros desarrolladores, sino que incluí un comentario sustituto en medio de una función. Debido a que los comentarios del código fuente se ignoran, puede usarlos para mantener el texto sustituto en el archivo (como una anotación para devolver allí o como ejemplo para alguien como explicación). No seas algo extraño, especialmente, especialmente en proyectos de código abierto que no eran terriblemente bien moderados. Alguien encontrará un fragmento menos estelar y usará un comentario para Deneg al autor.
// debería funcionar, pero de alguna manera lo hace. No quiero
// para arreglarlo porque quiero que todos vean lo malo que es.
O puede corregir el código, pero incluir el código, simplemente comentado, para que pueda mostrar su código, mientras se burla del autor anterior .// El código antiguo era tan malo que solo tengo que dejarlo para que lo vea.
// Lo arreglé. Mi código está debajo. Pero mira esto.
// Funcionar thematrix () {
// lima neo = maybetheone.data + theracle.data
// if theone ()! == neo
// return console.log (“tienes el regalo, pero parece que estás esperando algo”)
//}
Asegúrate de nunca hacer esto. Incluso si crees que eres divertido o te haces lucir bien, no lo es y no. El uso real del comentario del código es mantener su código a mano mientras intenta algo más. O para dar un ejemplo de lo que no ha funcionado antes, para que alguien no vuelva a intentarlo sin resultados. Comentarios Código fuente para WordPress En general, WordPress se roda en cuatro idiomas diferentes. HTML, CSS, PHP y JavaScript. Es imperativo asegurarse de usar los personajes adecuados para comentarios. Para html: en css:/ * cualquier número de líneas será un comentario cerrado */tanto php como javaScript tienen los mismos métodos para hacer Comentarios con una y más líneas: o <?
El comentario no se detendrá hasta el cierre */ conclusión Si está en trincheras todos los días, escribiendo código y presionando GitHub, su organización puede tener una guía de estilo para los comentarios que desea seguir. Sin embargo, si no, o si está solo, mantener estas cosas en su mente no solo aliviará su trabajo en el futuro, sino que ayudará a cualquiera que vaya después de usted. ¿Cuáles son sus consejos y trucos para aprovechar al máximo su comentario de código? Imagen presentada por el elemento por Skillup / Shutterstock.com