ESTÁNDARES DE CODIFICACIÓN

¿Qué son?: son normas y reglas que convienen los programadores para
especificar como debe escribirse el Código Fuente y así evitar la incomprensión
del mismo, en procesos posteriores de mantenimiento, actualizaciones y
reparación de errores de ejecución. Por otro parte, vale la pena aclarar, que el
establecimiento de estándares de codificación no son de uso o de carácter
obligatorio, no obstante, son una herramienta útil para combatir un mal epidemial
que sucede en los mantenimientos, la dificultad para realizar los mismo de manera
eficaz y eficiente.

Vale la pena anotar, que el establecimiento de Estándares de Codificación hace

que los programadores de un proyecto trabajen de manera coordinada, tanto así
que parezca que el código fue escrito por un solo programador.

¿Por qué son importantes?

Los Estándares de Codificación, no pretende limitar al programador en su

creatividad, ni que su trabajo sea más arduo o difícil, antes por el contrario, buscan
que el codificar se vuelva más sencillo incluso se puede volver intuitivo, y en este
orden de idea, vale la pena resaltar las siguientes razones por la que los mismos
son muy importante al momento de escribir el código.

 Facilitan la escritura del código.

 Evita a que se comentan mayor cantidad de errores debido a malas

prácticas de programación.

 Facilitan la lectura (entendimiento) y, por tanto, permiten que los diferentes

desarrolladores puedan tratar cada porción del mismo como si de su propio
código se tratara (el código se convierte en algo que pertenece al equipo,
no a un desarrollador determinado, con sus manías y sus fobias).

 Permiten un mantenimiento eficaz y eficiente de la aplicación.

 Porque permite escribir un código uniforme en proyectos que envuelvan

un equipo de ingeniería completo.

 Mejoran la apariencia estética y profesional de producto de trabajo (por

ejemplo, al no permitir nombres excesivamente largos, nombres cómicos o
las abreviaturas).
  Ayudar a evitar "conflictos de nombres" que podrían ocurrir cuando se
combina el producto del trabajo de diferentes organizaciones

¿Qué convenciones o estándares se deben usar?

Depende del entorno de desarrollo que estés usando. No es lo mismo desarrollar

en Java, que para la plataforma .NET, que en Phyton... De todas formas, y como
consejo, se debe de tener en cuenta que las convenciones/estándares de la
industria son mejores que los de tu empresa, los de tu empresa son mejores que
los de tu proyecto, los de tu proyecto son mejores que tu estándar personal y este,
a su vez, siempre será mejor que no usar ninguna convención/estándar.

ALGUNOS ESTÁNDARES A TENER EN CUENTA AL MOMENTO DE

CODIFICAR

1. Variables.

En programación, las variables son espacios reservados en la memoria que,

como su nombre indica, pueden cambiar de contenido a lo largo de la ejecución de
un programa. Una variable corresponde a un área reservada en la memoria
principal del ordenador.

Para que nuestro código sea más entendible y claro, el identificador de la variable
debe ser mnemotécnico, es decir que debe reflejar el uso dentro del programa de
la misma.

REGLAS Y CONSEJOS PARA EL NOMBRAMIENTO DE VARIABLES

Reglas, una variable no puede:

1. Tener el mismo nombre que una “palabra reservada” del lenguaje.

Explicación: los lenguajes de programación tienen “palabras reservadas“, o sea

que esas palabras solo pueden ser usadas por el programa, por eso llevan el
nombre de “reservadas“, pues si supongamos el caso de que un lenguaje de
programación “X” tiene sus palabras reservadas.. Entre las cuales está: “ingresar“,
entonces eso quiere decir que el usuario NO debe declarar una variable con el
nombre “ingresar“, porque va a tener conflictos más adelante.
 2. Sólo pueden ser letras, dígitos y el guión bajo o subguión.

Explicación: pues en los lenguajes de programación hay sintaxis que deben

cumplirse al pie de la letra, entonces dice que las variables solo pueden llevar
letras, numeros y el subguión, ejemplo:

La siguiente variable está bien declarada: programando19

La siguiente variable está mal declarada: %&programando-19

Vemos que insertó caracteres especiales, ademas de que uso el guión normal ( no
el subguión ), por lo tanto puede que el programa entienda que es una resta,
entonces está mal delcarado por sintaxis.

3. Deben comenzar por una caracter ( letra ).

Explicación: por sintaxis como ya hemos visto, deben cumplir con estas reglas,
entonces no se puede comenzar con un número, ya que se debe comenzar por
una letra como dice la regla, ejemplo:

La siguiente variable está bien declarada: pasoApaso

La siguiente variable está mal declarada: 89pasos

4. Deben iniciar con un caracter ( no numero ) como vimos en la regla 3, y

también puede comenzar con un guión bajo ( _ ), ejemplo:

La siguiente variable está bien declarada: _descuento

La siguiente variable está mal declarada: -descuento

La siguiente variable está mal declarada: descuento-

5. No se les pueden llevar espacios en blanco.

Explicación: las variables no pueden llevar espacios en blanco, solo pueden ser
separadas por un signo dedicado a ser usado como un espacio, el cual es el
subguión ( _ ), entonces en una variable cuando vean un subguión, practicamente
estan separando algo ( para que no parezca una ensalda ), ejemplo:

La siguiente variable está bien declarada: eddy_19

La siguiente variable está mal declarada: eddy 19

 6. No pueden llevar acento ( tilde ), ejemplo:

La siguiente variable está bien declarada: numero

La siguiente variable está mal declarada: número

NOMENCLATURA DE VARIABLES

Utilizar nombres de variables sencillos y comprensibles.

Es necesario nombrar las variables de manera que facilite la comprensión del

código fuente, manteniendo una cierta lógica dentro del modelo de negocio que
representan. Se utilizarán sustantivos escritos en minúsculas. Si el nombre de la
variable está formado por más de una palabra, a partir de la segunda palabra, la
primera letra de cada palabra deberá estar en mayúsculas. De esta manera, el
desarrollador obtendrá un código más intuitivo y sencillo de mantener.

Nombres de variables y programas

Nombres de variables

 Los nombres que se usen deben ser significativos.

 Los nombres deben estar en minúsculas, excepto la primera letra de cada

palabra a partir de la segunda.

 Una variable $aa o $a1 no significan nada. No hay problema en utilizarlo si

es una variable temporal que va a ser utilizada en las líneas siguientes,
pero si va a ser utilizada más lejos en el programa, debe tener un nombre
significativo.

SI NO

Nombre_Empleado
$nbeEmpleado NOMBRE
NbeEmpleado
 Variables globales

Se debe evitar el uso de variables globales ya que pueden ser modificadas

erróneamente y pueden causar errores muy difíciles de identificar. Si se usan,
para poder identificarlas, deben estar en mayúsculas. Ejemplo:

$BD
$EEE
$USUARIO

Corchetes e indentación

La indentación es algo que ayuda a darle claridad a un programa y es

INDISPENSABLE que se haga bien. Debe hacerse con "tabs" y no con espacios
en blanco.

Los corchetes de un bloque if, o switch, o for, deben ir en la misma línea de la

cláusula. A continuación mostramos la forma apropiada de hacerlo.

if ($edadCliente<$edadExigida){
instruccion1;
instruccion2;
} else {
instruccion3;
};

Ejemplo de indentación apropiada:

function verificarCondicion() {
if (condicion1) {
if (condicion2) {
while (condicion3) {
instruccion1;
};
};
instruccion2;
}else{
instruccion3;
};
 };

FUNCIONES

Nombramiento de Funciones

Nomenclatura de métodos, funciones y procedimientos

Nombrar a los métodos, funciones y procedimientos describiendo la acción que

realizan.

Los métodos, funciones y procedimientos se nombrarán describiendo la acción

que realizan mediante el uso de verbos. La primera letra del nombre deberá estar
en minúsculas. Si el nombre está formado por más de una palabra, a partir de la
segunda palabra la primera letra deberá estar en mayúsculas.

Nomenclatura de constantes

Nombrar las constantes siempre en mayúsculas.

Las constantes deben nombrarse todas en mayúsculas, separando las palabras
que formen parte del nombre con el carácter de subrayado (_).

Constantes y Variables globales

CONSTANTES

Se deben evitar constantes numéricas sin mucho significado. Para eso es

conveniente definir las constantes en el programa. Todos los caracteres deben
estar en mayúsculas y las palabras separadas por "_".

Por ejemplo:

SI NO

define("EDAD_VOTACION”, "18");
... if (18<$edad)
if (EDAD_VOTACION <= $edad)
 Nota: Nótese que es más natural preguntar
"$edad>=EDAD_VOTACION" que "EDAD_VOTACION <=
$edad", o "$i==0" que "0==$i", sin embargo la forma que
estamos utilizando es mucho más apropiada, ya que si por
casualidad, a uno se le olvida poner un doble igual (==) y se
utiliza un solo igual (=), el programa no va a dar un error, sino
que va a hacer algo completamente distinto a lo deseado. Por
eso, es muy buena práctica acostumbrarse a poner primero la
constante y luego la variable

COMENTARIOS DE CÓDIGO

Un comentario en programación es la línea de texto o nota incorporada en

nuestro código fuente que el compilador ignora.

Los comentarios en programación se utilizan para poner aclaraciones del código, y

así es más fácil de entender lo que hace, aunque también se utilizan para anular
parte de un código.

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?

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í:

1
// begin variable listing
2
var myvar = 1;

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 pueden 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.

1 if(callAjax($params)) { // successfully run callAjax with user parameters

2 ... code
3 }

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 límites 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.
1 /**
2 * @desc opens a modal window to display a message
3 * @param string $msg - the message to be displayed
4 * @return bool - success or failure
5 */
6 function modalPopup($msg) {
7 ...
8 }

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 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.

1 /**
2 * @desc this class will hold functions for user interaction
3 * examples include user_pass(), user_username(), user_age(),
4 user_regdate()
5 * @author Jake Rocheleau jakerocheleau@gmail.com
6 * @required settings.php
7 */
abstract class myWebClass { }

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.

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.

1 /** @group footer */

2 #footer { styles... }

1 /** @group footer, small fonts, columns, external links **/

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.

1
function getTheMail() {
2
// code here will build e-mail
3
/* run code if our custom sendMyMail() function call returns true
4
find sendMyMail() in /libs/mailer.class.php
5
we check if the user fills in all fields and message is sent! */
6
if(sendMyMail()) { return true; // keep true and display onscreen success
7
}
8
}
9

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.

1. 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?

1 $dir1 = "/home/"; // set main home directory

2 $myCurrentDir = getCurDirr(); // set the current user directory
3 $userVar = $get_username(); // current user's username

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 .

$(document).ready(function() {
1
$('.sub').hide(); // hide sub-navigation on pageload
2
3
/** check for a click event on an anchor inside .itm div
4
prevent the default link action so the page doesn't change on click
5
access the parent element of .itm followed by the next .sub list to
6
toggle open/close
7
**/
8
9
$('.itm a').live('click', function(e){
10
e.preventDefault();
11
$(this).parent().next('.sub').slideToggle('fast');
12
});
13
});

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.

2. 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.

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.

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!.

No hay que olvidar que el código y sus comentarios forman un conjunto. Así
que debemos prestar la debida atención a ambos apartados. Para que nuestro
código sea elegante, limpio y fácil de mantener, podemos seguir los siguientes
consejos.

DIEZ CONSEJOS PARA MEJORAR LOS COMENTARIOS DE CÓDIGO DE

FUENTE

1. Utiliza nombres descriptivos

Es una regla básica, que aunque no está directamente relacionada con los
comentarios, influye mucho en ellos. Nuestras variables, clases y métodos, deben
tener un nombre descriptivo.

Lo normal es que los nombres de las clases sean sustantivos que representen una
entidad (Cliente, Proveedor etc.). Los métodos representan una acción, por lo que
su nombre suele contener algún verbo (devolverNuevoCliente, calcularPrecioTotal
etc.). Además deberemos intentar que las variables, propiedades y parámetros,
tengan un nombre que describa el valor que contienen (totalclientes,
totalpresupuesto etc.).

¿Qué conseguimos con esto? Pues además de un código fuente mucho más
legible, conseguimos reducir el número de comentarios necesarios. Por ejemplo:

var cliente = servicioClientes.recuperarDatosCliente(id_cliente);

if (cliente.estaActivo)

cliente.UlitmoAcceso=Date.Now;

servicioDatos.guardaCliente(cliente);

}
Al usar nombres descriptivos el código no necesita comentarios adicionales.
Cualquier programador que revise el código, será capaz de hacerse una idea de lo
que hace el código.

2. Los comentarios tienen que ser útiles

No hace falta explicar cosas obvias. El código fuente en el 98% de los casos lo va
a leer otro programador. O al menos alguien con conocimientos de programación.
Por ejemplo:

// Comprobamos si el contador es 5

if (contador == 5)
Ese comentario no aporta nada. Mejor si lo eliminamos. Mejor todavía si no
llegamos ni a escribirlo.
 3. Piensa si un comentario es necesario antes de añadirlo

Si tenemos que añadir un comentario es mejor pensarlo un poco antes de hacerlo.

¿Por qué voy añadir este comentario? ¿Es realmente necesario? ¿Puedo
refactorizar mi código para evitarlo? Quizá el código que hemos escrito es
demasiado complejo y por eso necesita ser explicado. En ese caso podremos
separarlo en métodos más sencillos. Siempre siguiendo la norma de usar nombres
descriptivos.
Con esta simple idea, también podemos identificar posibles errores de diseño

4. Evita comentarios dentro de métodos o funciones

Puede ser útil comentar lo que hace un método antes de su declaración. Incluso
podemos comentar sus parámetros. Pero hay que tener en cuenta que debemos
comentar el "qué" y no el "cómo". Es decir, debemos explicar qué hace nuestro
método. El "cómo" hace el método su función ya va explicado en el código.

5. No comentes código eliminado

A veces nos vemos obligados a eliminar parte del código. Y a veces, en un

arranque de "por si acaso", comentamos el código eliminado, para no perderlo.
Esto es algo que no tiene sentido en el siglo XXI. Ya deberíamos tener un sistema
de control de código fuente para estas cosas. Y si no lo tenemos, tenemos
problemas más graves que los comentarios.

6. Piensa que los comentarios también hay que mantenerlos

Un comentario tiene que ser claro y explicar bien las cosas. Pero los comentarios
también hay que mantenerlos. Si describimos lo que hace un método, y en algún
momento la funcionalidad cambia, también tendremos que actualizar los
comentarios. Por tanto mejor que los comentarios sean breves y concisos.

7. Ten cuidado con los comentarios engañosos

Es algo que no suele hacerse a propósito, pero que puede darnos más de un
quebradero de cabeza. Tiene que ver con el punto anterior y el problema de no
mantener los comentarios. A veces porque nos dejamos algo por hacer, o por qué
una especificación ha cambiado, nuestro comentario queda obsoleto. O lo que es
peor, el comentario expresa algo distinto a lo que en realidad se está haciendo. Si
nos fiamos del comentario, podemos generar errores no esperados.
public int devolverEstadoCliente(){
// TO-DO
return 0;
}
Y luego en otra parte del código encontramos los siguientes
//Borramos el cliente si está desactivado
if (cliente.devolverEstadoCliente() == 0)
servicioDatos.borrarCliente(cliente);
En el ejemplo el problema se ve fácil porque el código está próximo. Pero si
tenemos el código repartido en distintas clases, podemos estar borrando cliente
sin querer.

8. Sigue siempre un mismo estilo

Es recomendable comentar el código siempre de la misma manera. Un estilo

definido ayuda a comprender el código a quién lo está leyendo. Si siempre
comentamos un método con una introducción y una descripción de los
parámetros, tendremos que ser constantes y hacerlo en todos los métodos. Si no
la persona que lo lea puede acabar confundido por la disparidad de criterios.

9. No dejes los comentarios para el final

En general a los que desarrollamos, no nos gusta comentar. Es algo aburrido, que
solemos dejar para más tarde. Pero procrastinar el comentado del código es una
mala idea por varias razones. La primera es que, al final, nos veremos obligados a
comentar un gran volumen de código de golpe. Eso es todavía más aburrido, y
nuestros comentarios serán peores. La segunda es que las ideas pierden frescura
según pasa el tiempo. Escribir comentarios de código que no acabamos de hacer
es más complicado y lleva más tiempo.
Mejor comenta a la vez que programas. O mejor, comenta antes de programar.
Escribiendo lo que tienes que hacer hacer, tendrás una mejor comprensión del
problema.

10. Es mejor ser educado

Esto depende de un poco del ámbito del código fuente. En ámbitos laborales,
deberemos ser serios y correctos. Y más si el código es para un cliente. Si el
código lo estamos haciendo para nosotros, los comentarios pueden tener un tono
más distendido. Eso sí, mejor evitar palabras malsonantes, porque nunca se sabe
quién puede leer el comentario.