tratamiento de textos (como loseditores de texto), para diferenciar elementos de texto (especialmente el llamado
código fuente) mediante diversos colores o estilos tipo- gráficos, dependiendo de las categorías sintácticas de sus términos, conforme a las reglas de algúnlenguaje formal
concreto.
Este resaltado se utiliza a modo de notación secunda- ria, habitualmente para mejorar la legibilidad del código fuente de programas o de textos escritos en algúnlenguaje de marcado, permitiendo aumentar la productividad de los programadores. Los estilos aplicados por defecto de- penden de cada programa informático, alguno de los cua- les permiten configurar los estilos e incluso reconocer di- versos lenguajes.
Presentación independiente del significado
La interpretación del texto no varía en absoluto al resaltar sus elementos. Los cambios en la representación del texto cumplen una función visual identificativa y no semántica, sólo se usan para transmitir información al lector humano. Por tanto, en el caso del código fuente de un programa, losintérpretesy loscompiladoreslo ignoran. No forman parte ni del lenguaje formal en sí, ni del texto, por lo que tampoco se guardan en el fichero, sino que se analiza cada vez que se carga.
34.1 Ejemplo
Abajo se muestra un trozo de código enC++:
// Bucle for normal for (int i=0; i<maximo; i++) { *(Una_estructura).un_campo = i+5; }
A veces, estos editores pueden resaltar las llaves, parén- tesis y corchetes de forma que al posicionar el cursor so- bre uno de ellos, se destacan los dos elementos, tanto el de apertura, como el de cierre ̶incluso conetiquetas HTML. Esto es de gran ayuda al escribir programas con gran número de anidamientos hechos con estos elemen- tos.
34.2 Programas con coloreado de
sintaxis
• Scintilla • Notepad++ • Notepad2 • SciTE • Geany • Vim • Emacs • gedit• El visor de código fuente de la mayoría de los navegadores web.
34.3 Véase también
• Editor de páginas web • Editor de texto
• WYSIWYG
• WYSIWYM
Capítulo 35
Comentario (informática)
/**
* Simple HelloButton() method. * @version 1.0
* @author john doe <[email protected]> */
HelloButton() {
JButton hello = new JButton( "Hello, wor hello.addActionListener( new HelloBtnList
// use the JFrame type until support for t // new component is finished
JFrame frame = new JFrame( "Hello Button" Container pane = frame.getContentPane(); pane.add( hello );
frame.pack();
frame.show(); // display the fra
}
Un ejemplo decódigo fuentedeJava, con comentarios de prólogo en rojo, comentarios entre líneas en verde. Código del progra-
ma en azul.
En la programación de computadoras, un comentario es una construcción del lenguaje de programación*[1]
destinada a incrustar anotaciones legibles al programa- dor en elcódigo fuentede unPrograma informático.*[2]
Estas anotaciones son potencialmente significativas pa- ra los programadores, pero usualmente ignorados por los
compiladoreseintérpretes.*[3]*[4]Los comentarios son
añadidos usualmente con el propósito de hacer el código fuente más fácil de entender con vistas a su mantenimien- to o reutilización. La sintaxis y reglas para los comenta- rios varían y usualmente son definidas en la especificación del lenguaje de programación.
Se ha de tener en cuenta que los comentarios necesitan mantenimiento igual que el código y, por tanto, que un comentario preciso y conciso es más fácil de mantener que uno largo, repetitivo y complicado.
Los comentarios tienen una amplia gama de posibles usos: desde la mejora del código fuente con descripcio- nes básicas hasta lageneración de documentaciónexter- na. También se utilizan para la integración con sistemas decontrol de versionesy otros tipos deherramientas de programaciónexternas.
La flexibilidad proporcionada por los comentarios da pie
a un amplio abanico de formas de uso distintas y a la in- clusión de información inútil dentro del código fuente. Para evitar este inconveniente, muchos programadores y analistas de software adoptan alguna de las “filosofías” o metodologías para la correcta utilización de los comen- tarios.
35.1 Información general
Los comentarios adoptan por norma general un formato o bien de“bloque”(también denominado de“prólogo” ) o bien de“fin de línea”(también denominado“inline” ).*[5]
Un comentario de bloque delimita una zona del código fuente en la cual es permitido expandirse a varias líneas de texto. Esta región se reconoce por un delimitador de
inicio y un delimitador de final del comentario. Algunos
lenguajes de programación admiten que los comentarios se aniden recursivamente (e.g., MATLAB), pero otros lenguajes no lo admiten (e.g.,Java).*[6]*[7]*[8]
Un comentario de fin de línea comienza con un delimita-
dor y continúa hasta el final de la línea de texto (es decir,
no es necesario un segundo delimitador). En otros casos, el comentario de fin de línea comienza en una cierta co- lumna dentro del código fuente no siendo necesario un delimitador.*[8]
Los delimitadores son una secuencia conocida de caracte- res y suelen ser distintos para los comentarios de bloque que para los de fin de línea. Por ejemplo, el lenguajeC++
usa, para los comentarios de bloque, los delimitadores /* y */ mientras que los comentarios de fin de línea utiliza el delimitador //. Otros lenguajes solamente admiten un tipo de comentario. Por ejemplo,ADAsolamente dispo- ne de comentarios de fin de línea mediante el delimitador -−.*[8]
35.2 Usos
La mejor manera de dar uso a los comentarios es ob- jeto de controversia con posiciones a menudo enfrenta- das.*[9]*[10]Hay una gran variedad de formas de escri-
bir comentarios y muchos comentaristas que ofrecen, en ocasiones, consejos contradictorios.*[10]
35.2.1
Planeación / Revisión
Los comentarios se pueden utilizar como una forma de
pseudocódigopara describir la intención antes de escri- bir el código real. En este caso se debe explicar la lógica detrás del código en lugar del código en sí mismo. /* itera hacia atrás por todos los elementos retornados por el servidor (estos deben ser procesados cronoló- gicamente)*/ for (i = (numElementsReturned - 1); i >= 0; i--){ /* procesa los datos de cada elemento */ updatePattern(i, returnedElements[i]); }
Si se deja este tipo de comentario luego de escribir el có- digo, se simplifica el proceso de revisión al permitir la comparación directa del código con los resultados pre- vistos. Una falacia lógica común es que el código fácil de entender hace lo que tiene que hacer.
35.2.2
Descripción de código
Los comentarios pueden ser utilizados para resumir el có- digo o para explicar la intención del programador. Se- gún esta escuela de pensamiento, re-explicar el código en lenguaje natural se considera superfluo y la necesidad de volver a explicar el código puede ser un signo de que es demasiado complejo y debe ser reescrito.
“No documentes mal código – re-escríbelo.”
*[11]
“Los buenos comentarios no repiten el código, ni lo explican. Estos aclaran su intención. Los comentarios deben explicar, a un nivel de abs- tracción más alto que el propio código, lo que se intenta conseguir”*[12]
Los comentarios también pueden ser utilizados para ex- plicar por qué un bloque de código no se ajusta a las con- venciones o las buenas prácticas. Esto está especialmente relacionado con proyectos de escaso tiempo de desarro- llo, o en la corrección de errores. Por ejemplo:
' Se asigna una segunda variable debido a que se pro- ducen errores ' en el servidor cuando se reutilizan los datos del formulario. No se encontró documentación ' sobre el comportamiento extraño del servidor, así que simplemente se codificó para resolverlo. vtx = server.mappath(“local settings”)
35.2.3 Descripción algorítmica
A veces, el código fuente contiene una solución nueva o digna de mencionarse a un problema específico. En tales casos, los comentarios pueden contener una explicación de la metodología. Estas explicaciones pueden incluir dia- gramas y pruebas matemáticas formales. Esto puede ser la explicación del código, en lugar de una clarificación de sus intenciones, pero otros encargados del manteni- miento del código pueden encontrar como fundamental esta explicación. Esto puede ser especialmente cierto en el caso de problemas de dominios de alta especialización; así como en optimizaciones, construcciones o llamadas a funciones de uso no cotidiano.*[13]
Por ejemplo, un programador puede agregar un comenta- rio para explicar por qué se eligió unOrdenamiento por inserciónen lugar de quicksort, pues el primero es, en teoría, más lento que el segundo. Esto podría escribirse de la siguiente manera:
list = [f (b), f (b), f (c), f (d), f (a), ...]; // Se requiere un ordenamiento estable, mientras el desempeño realmente no importa. insertion_sort (list);
35.2.4 Inclusión de recursos
Logotipos, diagramas y diagramas de flujoconsistentes en construcciones dearte ASCIIpueden ser insertados en el código fuente en forma de comentario.*[14]Además,
puede incrustarse como comentarios avisos de derechos de autor, fecha de creación, versión del producto, contac- to con el propietario y/o creador, etc..
El fragmento de código que sigue es un simple diagrama ASCII que representa el flujo de proceso para un script deadministración de sistemas contenido en unFichero Windows Scriptque se ejecuta enWindows Script Host
A pesar de que la sección que marca el código aparece co- mo un comentario, el diagrama de hecho aparece en una secciónXML CDATAsección, que técnicamente se con- sidera distinta de los comentarios, pero que puede servir para propósitos similares.*[15]
<!-- begin: wsf_resource_nodes --> <resource id="ProcessDiagram000"> <![CDATA[ HostApp (Main_process) | V script.wsf (app_cmd) --> ClientApp (async_run, batch_process) | | V mru.ini (mru_history) ]]> </resource>
Aún cuando este diagrama fácilmente podría haber sido incluido como un comentario, el ejemplo ilustra un ca- so en que el programador puede optar por no utilizar los comentarios, como una forma de incluir recursos en el código fuente.*[15]
35.3. ESTILOS 61
35.2.5
Depuración
Una práctica común entre programadores es comentar un fragmento de código, es decir, agregar delimitadores de modo que un bloque de código se convierta en un comen- tario, y por tanto no se ejecutará en el programa final. Es- to podría hacerse para excluir algunas piezas del código del programa o, de manera más común, para encontrar la causa de un error. Comentando sistemáticamente y eje- cutando partes del programa, la causa del error puede ser determinada, permitiendo su corrección. A continuación un ejemplo de cómo comentar código con el propósito de excluirlo:
if (opt.equals (“e”)) opt_enabled = true; /* if (opt.equals (“d”)) opt_debug = true; // */ //* if (opt.equals (“v” )) opt_verbose = true; // */
El fragmento de código de arriba sugiere que el progra- mador optó por desactivar la opción de depuración por alguna razón. Este estilo específico de comentario es más adecuado para la depuración. Un carácter de barra simple delante del delimitador de apertura es el que permite ha- bilitar o deshabilitar el comentarios de bloque completo. Muchos EIDs permiten agregar o remover rápidamente este tipo de comentarios con opciones del menú singula- res o atajos del teclado. El programador solamente debe marcar la parte de texto que desea comentar o descomen- tar y elegir la opción apropiada. Esto es particularmente útil con fragmentos grandes de código.
35.2.6
Generación de documentación
Las herramientas de programación en ocasiones incorpo- ran documentación y metadatos en los comentarios.*[16]
Estas pueden incluir las posiciones de inserción para la inclusión automática de archivos de cabecera, comandos para configurar el modo deresaltado de sintaxis*[17]o el
número de revisión del archivo.*[18]Estos comentarios
de control funcional son también conocidos comúnmen- te como anotaciones. Mantener la documentación dentro de comentarios en el código fuente es considerado co- mo una forma de simplificar el proceso de documenta- ción, así como un aumento en las posibilidades de que la documentación se mantendrá al día con los cambios en el código.*[19]Habitualmente este tipos de comentarios
requiere utilizar una sintaxis básica para que puedan ser interpretados por elgenerador de documentacióna dife- rencia de los comentarios anteriores donde no necesaria- mente se debe de utilizar una sintaxis predefinida.
Ddocpara el [[lenguaje de programacinet D]] ydoxygen, para ser usado con C/C++, JavaIDL y PHPDocpara
PHP.
C#,F#e implementan una característica similar llamada
comentarios XML, que son leídos porIntelliSensepara los ensamblados compilados del entorno.NET.*[20]
35.3 Estilos
Hay muchas alternativas cuando se considera como los comentarios deben aparecer en el código fuente. Para grandes proyectos, los estilos de los comentarios se agre- gan apenas comienzan el proyecto. Normalmente los pro- gramadores prefieren estilos que son consistentes, no obs- tructivos, fáciles de modificar, y difíciles de romper. Los siguientes fragmentos de código en C son solo un ejemplo de como los comentarios pueden variar de estilo, mientras todos contienen la misma información básica: /* Este es el cuerpo del comentario. Variante 1 */ /***********************************\ * * * Este es el cuerpo del comentario. * * Variante 2. * * * \************************************/
Factores tales como la preferencia personal, la flexibili- dad de las herramientas de programación, y otras consi- deraciones tienden a influir en las variantes de estilo uti- lizado en el código fuente.
35.3.1 Etiquetas
Algunasetiquetasse utilizan en los comentarios para ayu- dar en la indexación de los problemas comunes. Tales etiquetas son comúnmente resaltado de sintaxis y permi- te búsquedas con herramientas de programación común, como la utilidadgrepdeUNIX. Ejemplos de convenios etiqueta son:
• FIXME: para marcar código problemático potencial
que requiere una atención especial y/o revisión.
• NOTE: peligros potenciales para documentar el fun-
cionamiento interno del código y de indicar.
• TODO: para indicar las mejoras planificadas. • XXX: para advertir a otros programadores de código
problemático o equivoco.
Existe el riesgo de que las etiquetas se acumulan con el tiempo, es conveniente incluir la fecha y el propietario de etiqueta en el comentario de etiquetas para facilitar el seguimiento.
35.4 Curiosidades
Whitespacees unlenguaje de programación esotéricoen el cual la sintaxis consiste únicamente en espacios en blanco, tabulador y líneas nuevas, cualquier otro carácter es ignorado, por lo que en este lenguaje cualquier escrito es un comentario.
35.5 Ejemplos
35.5.1
Ensamblador
;comentario
35.5.2
Java
//comentario de línea /*comentario de bloque*/ /** co- mentario que será usado por javadoc */
35.5.3
C/C++
//comentario en línea /* comentario en bloque*/ #if 0 Co- mentario de bloque aunque el bloque contenga /* este tipo de comentarios */ #endif
35.5.4
Delphi
//comentario en línea { comentario en bloque } (* comentario en bloque *)
En delphi se pueden anidar comentarios de bloque siem- pre que no usen el mismo delimitador, e.g.
(* comentario en bloque { que contiene otros comentarios en bloque } // o de fin de línea y que es perfectamente válido *)
35.5.5
Lua
-- Un comentario de línea --[[ Un comentario de bloque ]]--
35.5.6
Ruby
#comentario =begin comentario de bloque =end
35.5.7
Python
#comentario
35.5.8
Perl
#comentario
35.5.9
Javascript
En archivo.js pueden darse las siguientes formas: //comentario en línea /* comentario en bloque */
35.5.10 código HTML
En las páginas webs .html se introduce el comentario en- tre
<!-- --> <!-- esto es un comentario en código HTML // -->
35.5.11 SQL
//esto es un comentario --este también /* y este en bloque */
35.5.12 Visual Basic
'comentario '''comentario XML
35.5.13 Pauscal
' Soy un sensual comentario.
35.5.14 PHP
//comentario en línea #este también /* comentario en blo- que */
35.5.15 Cobol
* Comentario
35.6 Referencias
[1] Para los propósitos de este artículo, los comentarios de un lenguaje de programación son tratados indistintamen- te de comentarios que aparecen enlenguajes de marcas,
archivos de configuraciónu otros contextos similares. Más aún, los lenguajes de marcas con frecuencia se relacio- nan de manera cercana con código de lenguajes de pro- gramación, especialmente en el contexto degeneración de código. Ver por ejemplo Ganguli, Madhushree (2002).
Making Use of Jsp (en inglés). Nueva York: Wiley.ISBN 0471219746., Hewitt, Eben (2003). Java for Coldfusion
Developers (en inglés). Upper Saddle River: Pearson Edu-
cation.ISBN 0130461806.
[2] Source code can be divided into program code (which con- sists of machine-translatable instructions); and comments (which include human-readable notes and other kinds of annotations in support of the program code).Penny Grubb, Armstrong Takang (2003). Software Maintenance: Con-
cepts and Practice (en inglés). World Scientific. pp. 7,
120–121.ISBN 981238426X.
[3] Algunos entornos de programación incluyen los comenta- rios como uno de los elementos de la sintaxis del lenguaje que son retenidos para procesamiento posterior, en lugar
35.7. ENLACES EXTERNOS 63
de ser descartados una vez han sido reconocidos por el procesador de lenguaje.
[4] Los comentarios deben ser indicados de tal manera que sea posible para el procesador de código fuente recono- cerlos como tal. Esto es usualmente simplificado al decir que los comentarios son “ignorados”(luego de ser reco- nocidos y desechados) por el procesador.
[5] Dixit, J.B. (2003). Computer Fundamentals and Pro-
gramming in C (en inglés). Laxmi Publications. ISBN 8170088828.
[6] Desmond, Higham (2005). MATLAB Guide (en inglés). SIAM.ISBN 0898715784.
[7] Vermeulen, Al (2000). The Elements of Java Style (en in- glés). Cambridge University Press.ISBN 0521777682. [8] «Using the right comment in Java»(en inglés). Consul-
tado el 24 de julio. Parámetro desconocido |añoacce3so= ignorado (ayuda)
[9] W. R., Dietrich (2003). Applied Pattern Recognition: Algo-
rithms and Implementation in C++ (en inglés). Springer.
p. 66.ISBN 3528355581. ofrece puntos de vista sobre el uso adecuado de comentarios en el código fuente [10] Keyes, Jessica (2003). Software Engineering Handbook
(en inglés). CRC Press. p. 256.ISBN 0849314798. dis- cute los comentarios y la ciencia de la documentación [11] The Elements of Programming Style,Kernighan&Plauger
[12] Code Complete,McConnell
[13] Spinellis, Diomidis (2003). Code reading: The Open
Source Perspective (en inglés). Addison-Wesley. ISBN 0201799405.
[14] «CodePlotter 1.6 - Add and edit diagrams in your code with this 'Visio-like' tool». Consultado el 24 de julio de 2007.
[15] Niederst, Jennifer (2006). Web Design in a Nutshell:
A Desktop Quick Reference (en inglés). O'Reilly.ISBN 0596009879.En ocasiones la diferencia entre un“comen- tario”y otros elementos de la sintaxis de un lenguaje de programación o de marcas implica matices sutiles. Nie- derst indica una situación tal al decir: “Unfortunately, XML software thinks of comments as unimportant infor- mation and may simply remove the comments from a do- cument before processing it. To avoid this problem, use an XML CDATA section instead.”
[16] Vease e.g., Wynne-Powell, Rod (2008). Mac Os X for
Photographers: Optimized Image Workflow for the Mac User (en inglés). Oxford: Focal Press. p. 243. ISBN 0240520270.
[17] Lamb, Linda (1998). Learning the VI Editor (en inglés). Sebastopol: O'Reilly & Associates.ISBN 1565924266. describe el uso de sintaxis modeline en los archivos de configuración de Vim
[18] Ver e.g., Berlin, Daniel (2006). Practical Subversion, Se-
cond Edition (en inglés). Berkeley: APress. p. 168.ISBN 1590597532.
[19] Ambler, Scott (2004). The Object Primer: Agile Model-
Driven Development with UML 2.0 (en inglés). Cambridge
University Press.ISBN 1397805218. [20] Murach. C# 2005. p. 56.
35.7 Enlaces externos
• 13 consejos para comentar tu código • Como escribir comentarios(en inglés)
Compatibilidad (informática)
La compatibilidad es la condición que hace que un
programay un sistema, arquitectura oaplicaciónlogren comprenderse correctamente tanto directamente o in- directamente (mediante un algoritmo). A este algorit- mo que hace que un programa logre ser comprendido por un sistema, arquitectura o aplicación se lo denomi- naemuladorpor el hecho de que es unintérpreteentre el programa y el sistema, arquitectura o aplicación.
36.1 Problemas de compatibilidad
Un problema de compatibilidad (incompatibilidad) surge a partir de la falta o mala interpretación de un programa por un algoritmo, esto conlleva a una mala ejecución de dicho programa o a la imposibilidad de ser ejecutado. Un ejemplo práctico:
Compatibilidad:
programa_orden_decir=(“Hola”) sistema> Hola El programa le indica una orden al sistema y el sistema la interpreta y la ejecuta sin problemas.
Incompatibilidad Caso A (Mala ejecución): programa_orden_decir=(“Hola”) sistema> Chau El programa le indica una orden al sistema y el sistema la interpreta pero de forma errónea, devolviendo un resul- tado no esperado.
Incompatibilidad Caso B (Imposibilidad de ejecución): programa_orden_da31s4s232sd2453ce sistema> Error El programa le indica una orden al sistema que para él es arbitraria y por ende no logra interpretarla.
36.2
Emulación
La emulación consiste en utilizar unalgoritmode por me- dio, denominadoemuladorque simula ser el sistema, ar- quitectura o aplicación para el cual el programa está pre- parado, el emulador modifica los comandos del programa en memoria para que el sistema pueda interpretarlo como si estuviera especialmente diseñado para él.
Un ejemplo:
Ejecución de orden del programa:
programa_orden_decir=(“huta”)
Ejecución del emulador:
emul transformar programa_orden_* en siste-