Comentarios en el código fuente: Consejos y mejores prácticas

Los desarrolladores que han pasado  tiempo en grandes proyectos comprenden la importancia de tener comentarios de código.

Cuando estas construyendo muchas características en la misma aplicación, las cosas tienden a complicarse, hay tantos bits de datos, incluyendo las funciones, las referencias a variables, los valores de retorno, parámetros … ¿cómo espera tenerlo todo presente?

(Fuente imagen: Fotolia )

No debería ser ninguna sorpresa, comentar tu código es esencial tanto en proyectos en solitario como en equipo, sin embargo, muchos desarrolladores no son conscientes de cómo hacer este proceso, yo he descrito algunos de mis propios trucos personales para crear comentarios ordenados y claros. Normas y plantillas de comentario variarán entre los desarrolladores pero en última instancia se tratará de hacer los comentarios limpios y legibles para explicar con más detalle las zonas confusas en el código.

Debemos comenzar a discutir algunas de las diferencias en el formato de comentario, esto le dará una mejor idea de qué tan detallado puede convertirse el código del proyecto. A continuación voy a ofrecer algunos consejos y ejemplos específicos que usted puede comenzar a usar de inmediato.

Estilos comentar: Una visión general

Cabe señalar que estas ideas presentadas son simplemente directrices hacia los comentarios más limpios, los lenguajes de programación individuales no establecen directrices o especificaciones de cómo configurar su documentación.

Dicho esto, los desarrolladores de hoy en día se han agrupado para dar formato a su propio sistema de código de comentar. Voy a ofrecer algunos estilos del corriente y entrar en detalles de su propósito.

Comentando en línea

Prácticamente cualquier lenguaje de programación sencilla ofrece comentarios en línea . Estos se limitan al contenido de una sola línea y sólo comentan el texto después de cierto punto. Así, por ejemplo en C / C ++ de comenzar un comentario en línea se haría así:

Esto es perfecto para tocar el código durante unos segundos para explicar la funcionalidad de una línea posiblemente confusa, si está trabajando con una gran cantidad de parámetros o llamadas a funciones que puede realizar una serie de comentarios en línea cerca. Pero el uso más beneficioso es una explicación simplista para la funcionalidad pequeña .

Note en lo anterior que  el código tendría que ser en una nueva línea después del paréntesis de apertura, de lo contrario todo sería atrapado en la misma línea de comentario. Evite salirse de los limites ya que por lo general no es necesario ver una sola línea de comentarios hasta el fondo de su página.

Los bloques descriptivos

Cuando es necesario incluir una gran explicación general una sola linea no es suficiente. Hay plantillas de comentarios pre-formateados usados en casi todas las áreas de la programación, se llaman Bloques descriptivos y se observan sobre todo en torno a las funciones y los archivos de las librerias. Siempre que configure una nueva función es una buena práctica  añadir un bloque descriptivo encima de la declaración .

El anterior es un ejemplo sencillo de un comentario función descriptiva. He escrito una función JavaScript llamada presumiblemente en ModalPopup que toma un solo parámetro. En los comentarios anteriores he usado una sintaxis similar a phpDocumentor donde cada línea es precedida con un «@» seguido de una tecla seleccionada, estos no van a afectar a su código de ninguna manera, por lo que podrían escribir @description en lugar de @desc y no cambia en absoluto.

Estas pequeñas etiquetas  en realidad se llaman tags de comentario las cuales están documentadas en gran medida en internet, no dude en hacer uno propio y utilizar éstas como desee a través de su código, me parece que ayudan a mantener el flujo de manera que pueda comprobar la información importante de un vistazo . También debe notar que he usado el /* */estilo bloque de comentar formato. Esto mantendrá todo mucho más limpio que la adición de una doble barra a partir de las cada línea.

Grupo/Clase Comentarios

Aparte de comentar las funciones y bucles, no se utilizan con tanta frecuencia. Donde realmente se necesita fuertes comentarios en bloque es en la cabeza de sus documentos o archivos de la biblioteca de back-end, es fácil ir sin cuartel y escribir documentación sólida para cada archivo en su sitio web, podemos ver esta práctica en muchos CMS como WordPress .

La zona superior de su página debe contener comentarios sobre el propio archivo, de esta manera se puede comprobar rápidamente dónde se está editando cuando se trabaja en varias páginas al mismo tiempo. Además, puede utilizar esta área como una base de datos para las funciones más importantes que necesitará fuera de la clase.

Se puede ver que he utilizado sólo una pequeña muestra de la clase de la falsa myWebClass. He añadido alguna información meta con mi nombre y dirección de correo electrónico para el contacto . Cuando los desarrolladores están escribiendo código fuente abierto esto es generalmente una buena práctica para que otros usuarios pueden ponerse en contacto con usted para la ayuda. Este es también un método sólido cuando se trabaja en equipos de desarrollo más grandes.

La etiqueta @required no es algo que he visto utilizar en otros lugares. He mantenido el formato en algunos de mis proyectos sólo en las páginas en las que he personalizado una gran cantidad de métodos, siempre que se incluyen páginas en un archivo que deben llegar antes de cualquier código de salida. Así que la adición de estos datos en el bloque principal comentario clase es una buena manera de recordar qué archivos son necesarios .

Comentarios de Código de Front-End

Ahora que hemos cubierto 3 importantes plantillas de comentario, vamos a ver algunos otros ejemplos. Hay muchos desarrolladores de frontend que han pasado de estática HTML en jQuery y CSS . Comentarios HTML no son tan decididos en comparación con aplicaciones de programación, pero cuando estás escribiendo librerias de estilos y guiones de la página cosas pueden causar problemas con el tiempo.

(Fuente imagen: Fotolia )

JavaScript sigue un método más tradicional de comentar similar a Java, PHP y C / C ++. CSS solamente utiliza los comentarios de estilo bloque delineadas por una barra y un asterisco .  Debes recordar que los comentarios se mostrarán abiertamente a sus visitantes, ya que ni CSS ni JS se analiza el lado del servidor, pero ninguno de estos métodos funciona muy bien para dejar detalles informativos en el código para volver otra vez.

Específicamente romper archivos CSS puede ser una tarea difícil, Vamos a profundizar en la creación de grupos de estilo antes de mencionar algunos consejos detallados para el código de comentarios.

Grupos de estilos CSS

Para aquellos que han sido diseñadores CSS desde hace años, es casi como una segunda naturaleza. Poco a poco memorizar todas las propiedades, la sintaxis, y construir su propio sistema para hojas de estilo, a través de mi propio trabajo he creado lo que yo llamo la agrupación, que sirve para emparejar bloques CSS similares en una sola área.

Cuando vayamos a editar el código CSS podemos encontrar fácilmente lo que necesitamos en unos pocos segundos. La forma en que va este grupo de estilos es totalmente propia y esa es la belleza de este sistema. Tengo unos estándares preestablecidos, que que he descrito a continuación:

• @resets – quitando márgenes por defecto del navegador, relleno, fuentes, colores, etc.
• @fonts – párrafos, encabezamientos, blockquotes, enlaces, código
• @navigation – el núcleo principal de los enlaces de navegación web
• @layout – envoltura, envase, barras laterales
• @header y @footer – estos pueden variar dependiendo de su diseño. Posibles estilos incluyen enlaces y listas no ordenadas, columnas de pie de página, encabezados, sub-navs

Al agrupar las hojas de estilo que has encontrado, el sistema de etiquetado puede ayudar mucho. Sin embargo a diferencia de PHP o JavaScript utiliza solo una etiqueta @group  seguida de una categoría o palabras clave. He incluido 2 ejemplos a continuación para que pueda tener una idea de lo que quiero decir.

Se podría añadir alternativamente algunos detalles adicionales en cada bloque de comentario, yo prefiero mantener las cosas simples y directas por lo que las hojas de estilo son fáciles de hojear.

4 Consejos para un mejor formato de un comentario

Hemos pasado la primera mitad de este artículo mirando los diversos formatos de código de comentarios. Ahora vamos a discutir algunos consejos generales para mantener su código limpio, organizado y fácil de entender.

1. Mantenga todo legible

A veces,a los desarrolladores se nos olvida que estamos escribiendo comentarios para los seres humanos, todos los lenguajes de programación que entendemos se construyen para las máquinas, por lo que puede ser tedioso convertir esto en texto simple, pero es importante tener en cuenta que no estamos aquí para escribir un trabajo de investigación a nivel universitario.

Aunque sólo sea un par de palabras son mejor que nada, le ayudará a tener presente cambios que con el tiempo seguramente se olvidarán. Puesto que no estas buscando en las mismas variables y nombres de funciones cada día se tiende a olvidar poco a poco la mayoría del código.

Como regla general, tómate algún tiempo para hacer una pausa y reflexionar antes de escribir . Pregúntate ¿qué es lo más confuso sobre el programa y cómo se puede explicar mejor que en el lenguaje «de prueba»? También considere por qué está escribiendo el código exactamente como es.

Deja un comentario sendero que conduce de nuevo a algunos otros archivos esto le ayudará a recordar funcionalidad más fácil.

2. aliviar algo de espacio

No puedo hacer suficiente hincapié en la importancia de los espacios en blanco, esto es muy importante para los desarrolladores de PHP y Ruby que están trabajando en los sitios web masivos con cientos de archivos. Vas a estar mirando este código durante todo el día ¿No sería bueno si pudieras leerlo a través de las áreas importantes?

A medida que se desplaza a través de archivos, este estilo de comentar  hace que encontrar y corregir errores de código sea cientos de veces más fácil.

Se podría realizar una tarea similar en el código dentro de una función en la que se está confundido acerca de cómo funciona, pero este método con el tiempo y el desorden del códigono hará una tarea facil,lo ideal es que la adición de un gran bloque de comentario de línea se encuentre alrededor de la zona de la lógica .

Esto es un pequeño fragmento de código jQuery dirigido a un deslizamiento de navegación submenú. El primer comentario es en línea para explicar por qué estamos ocultando todas las .subclases, por encima del controlador de eventos  he usado un comentario de bloque que dicta con sangría todo lo escrito en el mismo punto . Esto hace las cosas más bonitas y organizadas en lugar de la marca en los párrafos, sobre todo hará sus comentarios más fáciles para los demás.

3. Comentario mientras la codificación

Junto con el espacio apropiado este puede ser uno de los mejores hábitos para empezar. Nadie quiere ir hacia atrás en su código después de que se está trabajando y documentar cada pieza. La mayoría de nosotros ni siquiera quieren volver y documentar las áreas confusas, realmente hace falta ser un montón de trabajo.

(Fuente imagen: Fotolia )

Pero si se puede escribir los comentarios mientras estás codificando  todo será fresco en su mente . Normalmente los desarrolladores podemos quedar atascado en un problema y buscar en la web parece la solución más fácil, pero resolver tal problema da un momento de claridad, donde se logra  entender errores anteriores, este es el mejor momento para comentar abierta y honestamente acerca de su código.

Además esto te dará la práctica para acostumbrarte a comentar todos tus archivos. La cantidad de tiempo requerido para volver atrás y averiguar cómo funciona algo es mucho más grande después de que ya se ha construido la función. Tanto tú mismo como futuros compañeros, agradecerán dejar comentarios desde el principio. 

4. Tratar con errores de codificación

No todos podemos sentarnos frente a la computadora por horas escribiendo código. Supongo que podemos probar, ¡pero en algún momento tenemos que dormir!  En este escenario, es crucial que usted deje largos comentarios detallados acerca de donde dejo líneas y soluciones de código.

(Fuente imagen: Fotolia )

Incluso después de una noche de sueño lo puede sorprender lo difícil que es la codificación, por ejemplo, si usted está construyendo una página de carga de imágenes y tiene que dejarlo sin terminar, se debe comentar en qué parte del proceso lo dejó . ¿Si las imágenes son cargadas y están siendo almacenados en la memoria temporal? O tal vez ni siquiera se reconocen en el formulario de carga, o tal vez no se muestran correctamente en la página después de cargar.

Comentar los errores es importante por dos razones principales. En primer lugar puede fácilmente recoger donde lo dejó y volver a intentarlo con la cabeza fría, y en segundo lugar se puede diferenciar entre la versión de producción en directo de su sitio web y los campos de prueba . Recuerde que los comentarios se deben utilizar para explicar por qué estás haciendo algo , no es exactamente lo que hace.

Conclusión

Desarrollar aplicaciones web y software es una práctica satisfactoria, aunque sea difícil. Si eres  uno de los pocos desarrolladores que realmente comprende la construcción de software entonces es importante manejar comentarios para aumentar sus habilidades de codificación. Dejar comentarios descriptivos es sólo una buena práctica en el largo plazo , y es probable que ¡nunca te arrepentirás!.

 

 

:: Traducción de http://www.hongkiat.com/blog/source-code-comment-styling-tips/