{"id":8838,"date":"2017-05-10T13:53:14","date_gmt":"2017-05-10T13:53:14","guid":{"rendered":"http:\/\/www.skinatech.com\/portal\/?p=2593"},"modified":"2017-05-10T13:53:14","modified_gmt":"2017-05-10T13:53:14","slug":"comentarios-en-el-codigo-fuente","status":"publish","type":"post","link":"https:\/\/www.skinatech.com\/inicio\/comentarios-en-el-codigo-fuente\/","title":{"rendered":"Comentarios en el c\u00f3digo fuente: Consejos y mejores pr\u00e1cticas"},"content":{"rendered":"

Comentarios en el c\u00f3digo fuente: Consejos y mejores pr\u00e1cticas<\/h1>\n

Los desarrolladores que han pasado\u00a0 tiempo en grandes proyectos comprenden la importancia de tener comentarios de c\u00f3digo.<\/p>\n

Cuando estas construyendo muchas caracter\u00edsticas en la misma aplicaci\u00f3n, las cosas tienden a complicarse, hay tantos bits de datos, incluyendo las funciones, las referencias a variables, los valores de retorno, par\u00e1metros … \u00bfc\u00f3mo espera tenerlo todo presente?<\/p>\n

\"c\u00f3digo
\n<\/span><\/span>(Fuente imagen: Fotolia<\/a> )<\/em><\/p>\n

No deber\u00eda ser ninguna sorpresa, comentar tu c\u00f3digo es esencial tanto en proyectos en solitario como en equipo, sin embargo, muchos desarrolladores no son conscientes de c\u00f3mo hacer este proceso, yo he descrito algunos de mis propios trucos personales para crear comentarios ordenados y claros<\/strong>. Normas y plantillas de comentario variar\u00e1n entre los desarrolladores pero en \u00faltima instancia se tratar\u00e1 de hacer los comentarios\u00a0limpios y legibles<\/strong>\u00a0para explicar con m\u00e1s detalle las zonas confusas en el c\u00f3digo.<\/p>\n

Debemos comenzar a discutir algunas de las diferencias en el formato de comentario, esto le dar\u00e1 una mejor idea de qu\u00e9 tan detallado puede convertirse el c\u00f3digo del proyecto. A continuaci\u00f3n voy a ofrecer algunos consejos y ejemplos espec\u00edficos que usted puede comenzar a usar de inmediato.<\/p>\n

Estilos comentar: Una visi\u00f3n general<\/h2>\n

Cabe se\u00f1alar que estas ideas presentadas son simplemente directrices<\/strong> hacia los comentarios m\u00e1s limpios, los lenguajes de programaci\u00f3n individuales no establecen directrices o especificaciones de c\u00f3mo configurar su documentaci\u00f3n.<\/p>\n

Dicho esto, los desarrolladores de hoy en d\u00eda se han agrupado para dar formato a su propio sistema de c\u00f3digo de comentar. Voy a ofrecer algunos estilos del corriente y entrar en detalles de su prop\u00f3sito.<\/p>\n

Comentando en l\u00ednea<\/h2>\n

Pr\u00e1cticamente cualquier lenguaje de programaci\u00f3n sencilla ofrece comentarios en l\u00ednea<\/strong> . Estos se limitan al contenido de una sola l\u00ednea y s\u00f3lo comentan el texto despu\u00e9s de cierto punto. As\u00ed, por ejemplo en C \/ C ++ de comenzar un comentario en l\u00ednea se har\u00eda as\u00ed:<\/p>\n

\n
\n\n\n\n
\n
1<\/div>\n
2<\/div>\n
3<\/div>\n<\/td>\n
\n
\n
\/\/ begin variable listing<\/code><\/div>\n
var<\/code> myvar = 1;<\/code><\/div>\n
..<\/code><\/div>\n<\/div>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/div>\n

Esto es perfecto para tocar el c\u00f3digo durante unos segundos para explicar la funcionalidad de una l\u00ednea posiblemente confusa,<\/strong>\u00a0si est\u00e1 trabajando con una gran cantidad de par\u00e1metros o llamadas a funciones que puede realizar una serie de comentarios en l\u00ednea cerca. Pero el uso m\u00e1s beneficioso es una explicaci\u00f3n simplista para la funcionalidad peque\u00f1a<\/strong> .<\/p>\n

\n
\n\n\n\n
\n
1<\/div>\n
2<\/div>\n
3<\/div>\n<\/td>\n
\n
\n
if<\/code>(callAjax(<\/code>$params<\/code>)) { <\/code>\/\/ successfully run callAjax with user parameters<\/code><\/div>\n
\u00a0<\/code>... code <\/code><\/div>\n
}<\/code><\/div>\n<\/div>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/div>\n

Note en lo anterior que \u00a0el c\u00f3digo tendr\u00eda que ser en una nueva l\u00ednea despu\u00e9s del par\u00e9ntesis de apertura, de lo contrario todo ser\u00eda atrapado en la misma l\u00ednea de comentario.\u00a0Evite salirse de los limites<\/strong>\u00a0ya que por lo general no es necesario ver una sola l\u00ednea de comentarios hasta el fondo de su p\u00e1gina.<\/p>\n

Los bloques descriptivos<\/h2>\n

Cuando es necesario incluir una gran explicaci\u00f3n general una sola linea no es suficiente. Hay plantillas de comentarios pre-formateados usados en casi todas las \u00e1reas de la programaci\u00f3n, se llaman\u00a0Bloques descriptivos <\/strong>y se observan sobre todo en torno a las funciones y los archivos de las librerias. Siempre que configure una nueva funci\u00f3n es una buena pr\u00e1ctica \u00a0a\u00f1adir un bloque descriptivo encima de la declaraci\u00f3n<\/strong> .<\/p>\n

\n
\n\n\n\n
\n
1<\/div>\n
2<\/div>\n
3<\/div>\n
4<\/div>\n
5<\/div>\n
6<\/div>\n
7<\/div>\n
8<\/div>\n<\/td>\n
\n
\n
\/**<\/code><\/div>\n
\u00a0\u00a0<\/code>* @desc opens a modal window to display a message<\/code><\/div>\n
\u00a0\u00a0<\/code>* @param string $msg - the message to be displayed<\/code><\/div>\n
\u00a0\u00a0<\/code>* @return bool - success or failure<\/code><\/div>\n
*\/<\/code><\/div>\n
function<\/code> modalPopup(<\/code>$msg<\/code>) {<\/code><\/div>\n
...<\/code><\/div>\n
}<\/code><\/div>\n<\/div>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/div>\n

El anterior es un ejemplo sencillo de un comentario funci\u00f3n descriptiva. He escrito una funci\u00f3n JavaScript llamada presumiblemente en ModalPopup<\/em> que toma un solo par\u00e1metro. En los comentarios anteriores he usado una sintaxis similar a phpDocumentor<\/a> donde cada l\u00ednea es precedida con un \u00ab@\u00bb<\/em>\u00a0seguido de una tecla seleccionada, estos no van a afectar a su c\u00f3digo de ninguna manera, por lo que podr\u00edan escribir @description<\/code>\u00a0en lugar de @desc<\/code>\u00a0y no cambia en absoluto.<\/p>\n

Estas peque\u00f1as etiquetas\u00a0 en realidad se llaman tags de comentario<\/a><\/strong> las cuales est\u00e1n documentadas en gran medida en internet, no dude en hacer uno\u00a0propio y utilizar \u00e9stas como desee a trav\u00e9s de su c\u00f3digo, me parece que ayudan a mantener el flujo de manera que pueda comprobar la informaci\u00f3n importante de un vistazo<\/strong> . Tambi\u00e9n debe notar que he usado el \/* *\/<\/code>estilo bloque de comentar formato. Esto mantendr\u00e1 todo mucho m\u00e1s limpio<\/strong>\u00a0que la adici\u00f3n de una doble barra a partir de las cada l\u00ednea.<\/p>\n

Grupo\/Clase Comentarios<\/h2>\n

Aparte de comentar las funciones y bucles, no se utilizan con tanta frecuencia. Donde realmente se necesita fuertes comentarios en bloque<\/strong> es en\u00a0la cabeza de sus documentos o archivos de la biblioteca de back-end, es f\u00e1cil ir sin cuartel y escribir documentaci\u00f3n s\u00f3lida para cada archivo en su sitio web, podemos ver esta pr\u00e1ctica en muchos CMS como WordPress<\/a> .<\/p>\n

La zona superior de su p\u00e1gina debe contener comentarios sobre el propio archivo, de esta manera se puede comprobar r\u00e1pidamente d\u00f3nde se est\u00e1 editando<\/strong> cuando se trabaja en varias p\u00e1ginas al mismo tiempo. Adem\u00e1s, puede utilizar esta \u00e1rea como una base de datos<\/a> para las funciones m\u00e1s importantes que necesitar\u00e1<\/strong>\u00a0fuera de la clase.<\/p>\n

\n
\n\n\n\n
\n
1<\/div>\n
2<\/div>\n
3<\/div>\n
4<\/div>\n
5<\/div>\n
6<\/div>\n
7<\/div>\n<\/td>\n
\n
\n
\/** <\/code><\/div>\n
\u00a0\u00a0<\/code>* @desc this class will hold functions for user interaction<\/code><\/div>\n
\u00a0\u00a0<\/code>* examples include user_pass(), user_username(), user_age(), user_regdate()<\/code><\/div>\n
\u00a0\u00a0<\/code>* @author Jake Rocheleau jakerocheleau@gmail.com<\/code><\/div>\n
\u00a0\u00a0<\/code>* @required settings.php<\/code><\/div>\n
*\/<\/code><\/div>\n
abstract<\/code> class<\/code> myWebClass { }<\/code><\/div>\n<\/div>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n<\/div>\n

Se puede ver que he utilizado s\u00f3lo una peque\u00f1a muestra de la clase de la falsa myWebClass<\/code>. He a\u00f1adido alguna informaci\u00f3n meta con mi nombre y direcci\u00f3n de correo electr\u00f3nico para el contacto<\/strong> . Cuando los desarrolladores est\u00e1n escribiendo c\u00f3digo fuente abierto esto es generalmente una buena pr\u00e1ctica para que otros usuarios pueden ponerse en contacto con usted para la ayuda. Este es tambi\u00e9n un m\u00e9todo s\u00f3lido cuando se trabaja en equipos de desarrollo m\u00e1s grandes.<\/p>\n

La etiqueta @required<\/code>\u00a0no es algo que he visto utilizar en otros lugares. He mantenido el formato en algunos de mis proyectos s\u00f3lo en las p\u00e1ginas en las que he personalizado una gran cantidad de m\u00e9todos, siempre que se incluyen p\u00e1ginas en un archivo que deben llegar antes de cualquier c\u00f3digo de salida. As\u00ed que la adici\u00f3n de estos datos en el bloque principal comentario clase<\/em> es una buena manera de recordar qu\u00e9 archivos son necesarios<\/strong> .<\/p>\n

Comentarios de C\u00f3digo de Front-End<\/em><\/h2>\n

Ahora que hemos cubierto 3 importantes plantillas de comentario, vamos a ver algunos otros ejemplos. Hay muchos desarrolladores de frontend<\/em> que han pasado de est\u00e1tica HTML<\/a> en jQuery<\/a> y CSS<\/a>\u00a0. Comentarios HTML no son tan decididos en comparaci\u00f3n con aplicaciones de programaci\u00f3n, pero cuando est\u00e1s escribiendo librerias\u00a0de estilos y guiones de la p\u00e1gina cosas pueden causar problemas con el tiempo.<\/p>\n

\"css\"
\n<\/span><\/span>(Fuente imagen: Fotolia<\/a> )<\/em><\/p>\n

JavaScript sigue un m\u00e9todo m\u00e1s 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<\/strong> . \u00a0Debes recordar que los comentarios se mostrar\u00e1n abiertamente a sus visitantes, ya que ni CSS ni JS se analiza el lado del servidor, pero ninguno de estos m\u00e9todos funciona muy bien para dejar detalles\u00a0informativos en el c\u00f3digo para volver otra vez.<\/p>\n

Espec\u00edficamente romper archivos CSS puede ser una tarea dif\u00edcil, Vamos a profundizar en la creaci\u00f3n de grupos de estilo antes de mencionar algunos consejos detallados para el c\u00f3digo de comentarios.<\/p>\n

Grupos de estilos CSS<\/h2>\n

Para aquellos que han sido dise\u00f1adores\u00a0CSS desde hace a\u00f1os, 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\u00e9s de mi propio trabajo he creado lo que yo llamo la agrupaci\u00f3n, <\/strong>que sirve para emparejar bloques CSS similares en una sola \u00e1rea.<\/p>\n

Cuando vayamos a\u00a0editar el c\u00f3digo CSS podemos\u00a0encontrar f\u00e1cilmente lo que necesitamos en unos pocos segundos. La forma en que va este grupo de estilos\u00a0es totalmente propia\u00a0y esa es la belleza de este sistema. Tengo unos est\u00e1ndares preestablecidos, que que he descrito a continuaci\u00f3n:<\/p>\n