7

Me gustaría incluir los datos del creador del código. ¿Existe algún formato para comentar código de forma elegante o cada uno lo hace lo mejor que puede? Para mí lo intuitivo es dividirlo en incialización, procesamiento y mostrar resultados, pero no se si hay una forma globalizada.

//Nombre desarrollador,  ¿Tipo Licencia?

//Inicialización variables
int i=0;   //iniciar i
etc...

//Procesamiento datos
for....    //Procesamiento
miProcesado();
etc....

....
//Presentación de resultados
print(i);   // Mostrar resultados
miFuncion();

Gracias

5
  • Además de lo comentado por @Shassain, con lo cual estoy de acuerdo, yo recomiendo comentar fragmentos de código "complicados", líneas que hagan cosas "difíciles de ver a primera vista". Ten en cuenta que el día de mañana puede tocar tu código otro programador y se agradece poder entenderlo rápidamente. Commented el 24 may. 2018 a las 6:02
  • 1
    Los comentarios deben explicar el porqué de algo más que lo que hace. Échale un vistazo a esto: improvingsoftware.com/2011/06/27/…
    – Kiko_L
    Commented el 24 may. 2018 a las 6:19
  • 2
    Ya que tienes c# en tus etiquetas, comentarte que en C# si añades tres barras /// antes de un método en Visual Studio, automáticamente te genera un <summary> con los parametros de entrada y salida. Esto es muy útil a la hora de generar documentación tambien. Tienes mas info aqui
    – Pikoh
    Commented el 24 may. 2018 a las 7:56
  • No es necesario poner los datos del autor en el código, ni en l cabecera, es mas, no se acostumbra eso. Para colocar esa información tienes las propiedades del proyecto. Usa los comentarios par lo que es, comentar cosas del código, comentar algo que creas importante y que te pueda servir a ti y a alguien mas en un futuro. Aparte acostumbrate a documentar con comentarios xml, tanto en métodos como en propiedades y hasta la clase misma, y aparte sirve para el intellisense.
    – Luis
    Commented el 24 may. 2018 a las 12:51
  • Otra cosa que puedes hacer, es incluir un archivo de texto con información de desarrolladores, copyright, etc. así no "manchas" tu código con información que no es relevante al propio código. Hay casos donde eso no es posible, por ejemplo escribir procedimientos almacenados, así si que es bueno poner la información de quién hizo el procedimiento y hasta la fecha.
    – Luis
    Commented el 24 may. 2018 a las 20:40

2 respuestas 2

3

Generalmente no es necesario comentar cada linea código, existen cierto estandar para realizar estos. Por Ejemplo:

Si deseas poner los datos del archivo junto a los del autor lo recomendable es ponerlo en la cabecera o inicio del archivo.

/** 
 * Mylibreria v1.1.5 |
 * (copyright) Autor MyEmpresa junto a contribuidores |
 * Mylibreria.com/license
 */

Posterior a esto lo recomendable es tener solo comentarios en las funciones que tengas, explicando para que sirve, cuales son sus parametros con ejemplo y cual es el valor de retorno.

Ejemplo:

/**
 * @funcion sumar_multiplicar
 * @descripcion realiza la siguiente formula (A + B)*C
 * @parametro int  A
 * @parametro int  B
 * @parametro int  C
 * @return int (A + B)*C
 */
 public int sumar_multiplicar(int a,int b, int c){
     return (a+b)*c;
 }

Con eso bastaría los comentarios, es una forma profesional de poner comentarios sin que afecte el performance de tu codigo.

EDICION:

Cuando se habla de performance del código(rendimiento del código), lo digo porque muchos de los lenguajes que etiquetas (java,javascript,c#) son del alto nivel, dichos lenguajes dependen de lenguajes de medio(c,basic,cobol) y bajo(assembler) nivel, entonces este ultimo es el que se encarga de separar codigo valido de comentarios(el cual lleva su tiempo de traducion por asi decirlo), para posteriormente llevarlo a lenguaje máquina(lenguaje binario ejecutado directamente en el CPU).

Como veras es un poco largo el camino que toma el lenguaje de alto nivel para llegar a ejecutarse en la CPU, Razón por la cual NO recomiendo poner tantos comentarios.

El códigos pequeños (de 0-10000 lineas código sumando los comentarios, digamos a un 50% de comentario) no se verán dificultades, pero de todos modos el traducir los comentarios tomara la mitad del tiempo de ejecución, ya con códigos mas grandes (10000-100000 lineas código) el tiempo de ejecución si se notara y se te presentara dificultades.

Entonces, si el deseo es comentar-explicar varias lineas código; es valido para cuando uno es docente que enseña a programar, cosa que dará facilidad de entendimiento a los estudiantes. Pero en caso de que el proyecto sea profesional y grande solo se comentan las funciones, ya que estoy seguro que cualquier otro compañero sabrá entenderlo, y si el deseo es documentarlo puedes hacer una pagina donde se explique a detalle o un simple documento de enseñanza en formato pdf o algo asi pero no en el codigo.

5
  • ¿Qué cosa es "performance de código"? Los comentarios se agregan donde se sienta que se requiere, hay que recordar que una cosa son los comentarios XML y otra los comentarios dentro de código, que también son necesarios a veces.
    – Luis
    Commented el 24 may. 2018 a las 12:42
  • Por cierto, muy mal recomendar eso de "lo recomendable es tener solo comentarios en las funciones que tengas", no hay que fomentar malas prácticas. Lo recomendable es documentar lo mejor posible, mas si es código que se piense utilizar como api pública, y/o se trabaja en equipo. Métodos, clases, propiedades, hay que acostumbrarse a documentar, si el día de mañana le toca trabajar en una empresa ya va con buenas prácticas y no va a tener problemas documentando. Y por cierto, en .net no se usan ese tipo de comentarios para documentar métodos, se usan las /// para generar xml
    – Luis
    Commented el 24 may. 2018 a las 12:56
  • Hombre, a menos que escribas kilómetros de comentarios eso ni lo notarás. Tengo soluciones con bastantes proyectos (hasta 20), con comentarios de todo tipo y te aseguro que no lo notas, y estamos hablando que con Roslyn el compilador está todo el rato haciendo su trabajo.
    – Luis
    Commented el 24 may. 2018 a las 19:54
  • tengo mas de 20 años desarrollando, actualmente trabajo en una empresa donde habemos un equipo de desarrollo. No, no estoy aprendiendo a programar, simplemente recomiendo buenas prácticas a los que van empezando.
    – Luis
    Commented el 24 may. 2018 a las 20:26
  • Continuemos el debate en el chat.
    – Shassain
    Commented el 24 may. 2018 a las 20:27
-1

Para esas cosas puedes guiarte por, por ejemplo, github, donde en el proyecto agrega un archivo de texto con la licencia (no va dentro del código). Un ejemplo: https://github.com/facebook/react/blob/master/LICENSE, igual puedes agregar un archivo con la información de los desarrolladores.

En cuanto a comentarios, ya depende de ti como escribirlos. También depende del lenguaje e incluso del entorno que utilices.

Cuando vas a documentar tu código trata de hacerlo como si lo escribieras para tu yo del futuro, porque te puedo asegurar que por mas bien que escribas el código, si lo dejas un tiempo aparcado y lo quieres retomar, te vas a tardar en volver a entender ciertas partes del código. Tampoco se trata de comentar cada línea de código, eso tan malo como no comentar, simplemente comenta donde pienses que merece la pena una explicación de porqué escribiste esa parte del código. Por ejemplo, en un ciclo for no pongas "aquí recorro toda la lista", eso no sirve de nada.

Aparte aprovecha las herramientas de tu entorno de desarrollo, tanto en java como en los lenguajes de .net tienes cosas como intellisense, que permite generar información de métodos, propiedades y tipos utilizando los comentarios xml que escribes en tu código (con /// en c#, /** */ en java, etc).

Aparte, dependiendo del lenguaje y del entorno de desarrollo, puedes utilizar cierto tipo de comentarios que te ayudarán mas. Por ejemplo, en c# y visual studio, si escribes un comentario así: "//TODO Falta validar", estás indicando un comentario tipo "TODO", es decir, un comentario de que ahí tienes que hacer algo, y visual studio te va a mostrar en una ventana todos los lugares donde encuentra el comentario TODO (menú ver -> Lista de tareas).

Igual los entornos de desarrollo modernos como eclipse, visual studio, o incluso visual studio code, permiten instalar extensiones que pueden, por ejemplo, ocultar los comentarios, así trabajas viendo solo tu código, pero también puedes tenerlo comentado. Yo utilizo estas en visual studio:

  • NoComments : Te oculta los comentarios y deja solo un pequeño ícono, que al pone el cursor del ratón sobre este, te muestra el comentario

  • Better Comments Puedes hacer que los comentarios tengan transparencia y cambiar el tamaño de la letra de los comentarios (por ejemplo, hacerlos mas pequeños).

Por último, salvo que el lenguaje sea interpretado como javascript, no tienes que preocuparte por el "rendimiento" añadiendo comentarios, los lenguajes como c#, java y otros que son compilados y no interpretados tienen varios procesos antes de crear el archivo executable binario (exe, dll, etc), y uno de los primeros pasos, el pre-procesador, se encarga de eliminar los comentarios. Aparte, compiladores modernos como Roslyn en visual studio 2015/2017, están compilando en tiempo real tu código todo el tiempo, así que simplemente omiten las líneas de código que son comentarios.

Tu Respuesta

By clicking “Publica tu respuesta”, you agree to our terms of service and acknowledge you have read our privacy policy.

¿No es la respuesta que buscas? Examina otras preguntas con la etiqueta o formula tu propia pregunta.