Código fuente Comentar Consejos de estilo y mejores prácticas
Los desarrolladores que han pasado algún tiempo en grandes proyectos entienden la importancia de los comentarios de código. Cuando construyes muchas funciones en la misma aplicación, las cosas tienden a complicarse. Hay tantos bits de datos que incluyen funciones, referencias de variables, valores de retorno, parámetros ... ¿cómo se espera que se mantengan al día??
No debería sorprender que comentar su código sea esencial, tanto en proyectos individuales como en equipo. Pero muchos desarrolladores desconocen cómo llevar a cabo este proceso. He esbozado algunos de mis propios trucos personales para creando comentarios ordenados y ordenados de código. Los estándares y las plantillas de comentarios variarán entre los desarrolladores, pero en última instancia, debe esforzarse por alcanzar Comentarios limpios y legibles para explicar con más detalle las áreas confusas en su código.
Deberíamos comenzar a discutir algunas de las diferencias en el formato de comentarios. Esto le dará una mejor idea de lo detallado que puede llegar a ser con el código del proyecto. Luego, le ofreceré algunos consejos y ejemplos específicos que puede comenzar a utilizar de inmediato.!
Estilos de comentarios: una visión general
Cabe señalar que estas ideas presentadas son meramente pautas hacia comentarios más limpios. Los lenguajes de programación individuales no establecen pautas o especificaciones sobre cómo configurar su documentación.
Dicho esto, los desarrolladores de hoy en día se han agrupado para formatear su propio sistema de comentarios de código. Ofreceré algunos estilos principales y detallaré su propósito..
Comentarios en línea
Prácticamente cada lenguaje de programación único ofrece comentarios en línea. Estos están limitados a contenido de una sola línea y solo comentan el texto después de un cierto punto. Entonces, por ejemplo, en C / C ++, comienza un comentario en línea como este:
// comenzar la lista de variables var myvar = 1;…
Esto es perfecto para chiming en el código durante unos segundos para explicar la funcionalidad posiblemente confusa. Si está trabajando con muchos parámetros o llamadas a funciones, puede colocar una gran cantidad de comentarios en línea cerca. Pero el uso más beneficioso es un Explicación simple para pequeñas funcionalidades..
if (callAjax ($ params)) // ejecuta satisfactoriamente callAjax con parámetros de usuario ... código
Tenga en cuenta que, sobre todo, el código debería estar en una nueva línea después del soporte de apertura. De lo contrario, todo quedaría atrapado en la misma línea de comentarios.! Evitar ir por la borda ya que por lo general no necesita ver comentarios de una sola línea en toda su página, pero especialmente para confusiones en su código, es mucho más fácil colocarlos en el último minuto..
Bloques descriptivos
Cuando necesita incluir una explicación amplia, generalmente un solo trazador de líneas no hará el truco. Existen plantillas de comentarios preformateadas que se utilizan en cada área de la programación.. Bloques descriptivos Se ven sobre todo alrededor de las funciones y archivos de la biblioteca. Siempre que configure una nueva función, es una buena práctica Añadir un bloque descriptivo encima de la declaración..
/ ** * @desc abre una ventana modal para mostrar un mensaje * @param string $ msg - el mensaje que se mostrará * @return bool - éxito o fracaso * / function modalPopup ($ msg) …
Arriba hay un ejemplo simple de un comentario de función descriptiva. He escrito una función presumiblemente en JavaScript llamada modalpopup que toma un solo parámetro. En los comentarios anteriores, he usado una sintaxis similar a phpDocumentor donde cada línea está precedida por una @ símbolo seguido de una tecla seleccionada. Estos no van a afectar su código de ninguna manera, por lo que podría escribir @descripción en lugar de @desc sin cambios en absoluto.
Estas pequeñas llaves se llaman en realidad etiquetas de comentarios que están documentados en gran medida en el sitio web. Siéntase libre de crear su propio y usar estos como desee a lo largo de su código. Encuentro que ayudan a que todo fluya tan Puedo revisar información importante de un vistazo. También deberías notar que he usado el / * * / Formato de comentario de bloque de estilo. Esto mantendrá todo mucho mas limpio que agregar una barra doble que comienza en cada línea.
Grupo / Comentarios de clase
Además de comentar las funciones y los bucles, las áreas de bloque no se utilizan con tanta frecuencia. Donde realmente necesites fuerte bloquear comentarios están a la cabeza de sus documentos de fondo o archivos de biblioteca. Es fácil ir completamente y escribir documentación sólida para cada archivo en su sitio web. Podemos ver esta práctica en muchos CMS como WordPress.
El área superior de su página debe contener comentarios sobre el archivo en sí. De esta manera puedes revisa rápidamente dónde estás editando cuando se trabaja en varias páginas al mismo tiempo. Adicionalmente puedes usar esta área como Una base de datos para las funciones más importantes que necesitarás. fuera de la clase.
/ ** * @desc esta clase contendrá funciones para la interacción del usuario * los ejemplos incluyen user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / clase abstracta myWebClass
Puedes ver que he usado solo una pequeña clase de muestra para el falso myWebClass código. He añadido alguna información meta Con mi nombre y dirección de correo electrónico de contacto.. Cuando los desarrolladores escriben código fuente abierto, generalmente es una buena práctica, por lo que otros pueden contactarlo para obtener asistencia. Este es también un método sólido cuando se trabaja en equipos de desarrollo más grandes..
La etiqueta @necesario no es algo que haya visto usado en otros lugares. He mantenido el formato en algunos de mis proyectos, solo en páginas donde he personalizado muchos métodos. Cada vez que incluya páginas en un archivo, éstas deben aparecer antes de generar cualquier código. Así que agregar estos detalles en el bloque de comentarios de la clase principal es una buena manera de recuerda qué archivos son necesarios.
Código de front-end comentando
Ahora que hemos cubierto 3 plantillas de comentarios importantes, veamos algunos otros ejemplos. Hay muchos desarrolladores frontend que han pasado de HTML estático a jQuery y al código CSS. Los comentarios HTML no son tan útiles en comparación con las aplicaciones de programación, pero cuando se escriben bibliotecas de estilos y scripts de página, las cosas pueden complicarse con el tiempo.
JavaScript sigue un método más tradicional de comentar similar a Java, PHP y C / C++. CSS solo utiliza los comentarios de estilo de bloque delineados por una barra y un asterisco. Debe recordar que los comentarios se mostrarán abiertamente a sus visitantes, ya que ni CSS ni JS están analizados en el lado del servidor, pero cualquiera de estos métodos funciona muy bien para dejar tidbits informativos en su código para volver a.
Específicamente romper archivos CSS puede ser una tarea. Todos estamos familiarizados con dejar un comentario en línea para explicar una solución para Internet Explorer o Safari. Pero creo que los comentarios de CSS se pueden usar en el nivel que jQuery y PHP usan. Vamos a profundizar en la creación de grupos de estilos antes de tocar algunos consejos detallados para comentar códigos..
Grupos de estilo CSS
Para aquellos que han estado diseñando CSS durante años, casi viene como una segunda naturaleza. Poco a poco memorizará todas las propiedades, la sintaxis y construirá su propio sistema para las hojas de estilo. A través de mi propio trabajo he creado lo que llamo. agrupamiento para emparejar bloques CSS similares en un área.
Cuando vuelvo a editar CSS, puedo encontrar fácilmente lo que necesito en unos segundos. La forma en que elija agrupar estilos depende totalmente de usted, y esa es la belleza de este sistema. Tengo algunos estándares preestablecidos que he descrito a continuación:
- @resets - eliminando márgenes, rellenos, fuentes, colores, etc. del navegador predeterminados.
- @fonts - párrafos, encabezados, blockquotes, enlaces, código
- @navigation - los principales enlaces de navegación del sitio web principal
- @layout - contenedor, contenedor, barras laterales
- @header & @footer: estos pueden variar según su diseño. Los estilos posibles incluyen enlaces y listas desordenadas, columnas de pie de página, encabezados, sub-navs
Al agrupar hojas de estilo he encontrado el sistema de etiquetado puede ayudar mucho Sin embargo, a diferencia de PHP o JavaScript utilizo una sola @grupo etiqueta 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.
/ ** pie de grupo @ / pie de página estilos…
/ ** Pie de página de grupo, fuentes pequeñas, columnas, enlaces externos ** /
Alternativamente, podría agregar un poco de detalle adicional en cada bloque de comentarios. Yo elijo mantener las cosas simples y directas Así que las hojas de estilo son fáciles de hojear. Comentar tiene que ver con la documentación, siempre y cuando entiendas la escritura, es bueno ir!
4 consejos para mejorar el estilo de comentario
Hemos pasado la primera mitad de este artículo analizando los distintos formatos para comentar códigos. Discutamos ahora algunos consejos generales para mantener su código limpio, organizado y fácil de entender..
1. Mantenga todo legible
A veces como desarrolladores nos olvidamos de eso. Estamos escribiendo comentarios para que los humanos lean.. Todos los lenguajes de programación que entendemos están diseñados para máquinas, por lo que puede ser tedioso convertirlos en texto simple. Es importante tener en cuenta que no estamos aquí para escribir un trabajo de investigación de nivel universitario, pero solo dejando propinas!
función getTheMail () // el código aquí generará el código de ejecución del correo electrónico / * si nuestra llamada personalizada de la función sendMyMail () devuelve true find sendMyMail () en /libs/mailer.class.php, verificamos si el usuario llena todos los campos y el mensaje es enviado! * / if (sendMyMail ()) return true; // mantener la verdad y mostrar el éxito en pantalla
Incluso solo un par de palabras son mejor que nada. Cuando vuelves a editar y trabajas en proyectos en el futuro, a menudo es sorprendente lo mucho que olvidarás. Como no está viendo las mismas variables y nombres de funciones todos los días, tiende a olvidar lentamente la mayoría de su código. Asi puedes nunca dejes demasiados comentarios! Pero puedes dejar demasiados malos comentarios..
Como regla general, tómate un tiempo para hacer una pausa y reflexionar antes de escribir. Pregúntese ¿Qué es lo más confuso del programa? y ¿Cómo puedes explicarlo mejor en “tonto” idioma? También considera ¿Por qué estás escribiendo el código exactamente como eres?.
Algunos de los errores más confusos aparecen cuando se olvida el propósito de las funciones personalizadas (o de terceros). Deja un comentario que conduce de vuelta a algunos otros archivos Si esto te ayudará a recordar la funcionalidad más fácil..
2. aliviar algo de espacio!
No puedo enfatizar lo suficiente lo importante espacio en blanco puede ser. Esto va doblemente cierto para desarrolladores de PHP y Ruby que trabajan en sitios web masivos con cientos de archivos. ¡Estarás mirando este código todo el día! ¿No sería genial si pudiera hojear las áreas importantes??
$ dir1 = "/ home /"; // establece el directorio de inicio principal $ myCurrentDir = getCurDirr (); // establece el directorio de usuario actual $ userVar = $ get_username (); // nombre de usuario actual
En el ejemplo anterior, notará el relleno adicional que he colocado entre los comentarios y el código en cada línea. A medida que se desplaza por los archivos, este estilo de comentarios claramente se destacan. Eso hace que encontrar errores y corregir su código cientos de veces sea más fácil cuando los bloques variables son tan limpiar.
Podría realizar una tarea similar en el código dentro de una función en la que está confundido acerca de cómo funciona, pero este método eventualmente saturará su código con comentarios en línea, ¡y eso es exactamente lo contrario de ordenado! Recomiendo en este escenario Añadiendo un gran comentario de línea de bloque alrededor del área de la lógica..
$ (document) .ready (function () $ ('. sub'). hide (); // hide sub-navigation on pageload / ** busca un evento de clic en un ancla dentro de .itm div impide el enlace predeterminado para que la página no cambie al hacer clic, acceda al elemento padre de .itm seguido de la siguiente lista .sub para abrir / cerrar ** / $ ('. itm a'). live ('clic', función (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('fast'););); Esta es una pequeña parte del código jQuery que se dirige a una navegación deslizante de submenú. El primer comentario está en línea para explicar por qué estamos ocultando todas las .sub clases Sobre el controlador de eventos de clics en vivo, he usado un comentario de bloqueo y Ha sangrado toda la escritura hasta el mismo punto.. Esto hace que las cosas sean más bonitas que los párrafos corrientes, especialmente para otros que lean sus comentarios.
3. Comenta mientras codificas
Junto con el espacio adecuado, este puede ser uno de los mejores hábitos para entrar. Nadie quiere volver sobre su programa después de que esté funcionando y documentar cada pieza. ¡La mayoría de nosotros ni siquiera queremos volver y documentar las áreas confusas! Realmente toma mucho trabajo.
Pero si puedes escribir los comentarios mientras estás codificando. todo aún estará fresco en tu mente. Normalmente, los desarrolladores se atascan en un problema y recorren la web para encontrar la solución más fácil. Cuando llegas al momento Eureka y resuelves un problema, generalmente hay un momento de claridad en el que comprendes tus errores anteriores. Este seria el mejor época Dejar comentarios abiertos y honestos sobre tu código..
Además, esto le dará práctica para acostumbrarse a comentar todos sus archivos. La cantidad de tiempo requerido para volver y descubrir cómo funciona algo es mucho mayor después de que ya hayas creado la función. Tanto tu yo futuro como tus compañeros te agradecerán por dejar comentarios antes de tiempo..
4. Tratar con errores de Buggy
No todos podemos sentarnos frente a la computadora durante horas escribiendo el código. Supongo que podemos intentarlo, pero en algún momento tenemos que dormir! Es probable que tengas que separarte de tu código del día con algunas funciones que aún están dañadas. En este escenario es crucial que usted Deja comentarios largos y detallados sobre dónde dejaste las cosas..
Incluso después de una noche de sueño reparador, se sorprenderá de lo difícil que puede ser volver al ritmo de la codificación. Por ejemplo, si está creando una página de carga de imágenes y tiene que dejarla sin completar, deberías comentar sobre en qué parte del proceso te quedaste. ¿Las imágenes se cargan y se almacenan 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 la carga.
Comentar errores es importante por dos razones principales. Primero puedes recoger fácilmente donde lo dejaste y vuelva a intentarlo de nuevo para solucionar el (los) problema (s). Y en segundo lugar puedes diferenciar entre la versión de producción en vivo de su sitio web y los campos de prueba. Recuerde que los comentarios deben ser utilizados para explica por qué estás haciendo algo, no exactamente lo que hace.
Conclusión
El desarrollo de aplicaciones web y software es una práctica satisfactoria, aunque difícil. Si usted es uno de los pocos desarrolladores que realmente entiende el software de construcción, entonces es importante madurar con sus habilidades de codificación.. Dejar comentarios descriptivos es solo una buena práctica a largo plazo, y es probable que nunca te arrepientas!
Si tiene sugerencias para comentarios de códigos más claros, háganoslo saber en el área de discusión a continuación.!
