Los comentarios que debe de tener tu código a la hora de programar

Algunos comentarios son necesarios o beneficiosos. Veremos algunos que se consideran importantes. Tenga en cuenta, sin embargo, que el único comentario realmente bueno es el comentario que no tiene que escribirse.

comentarios

comentarios

Comentarios Legales

A veces nuestros estándares corporativos de codificación nos obligan a escribir ciertos comentarios por motivos legales. Por ejemplo, los derechos de autor y las declaraciones de autor son necesarios y razonables, son cosas para poner en un comentario al comienzo de cada archivo de origen.

Aquí, por ejemplo, es el encabezado de comentarios estándar que ponemos al principio de cada archivo fuente.

// Copyright (C) 2003,2004,2005 por Object Mentor, Inc. Todos los derechos reservados.

// Liberado bajo los términos de la Licencia Pública General GNU versión 2 o posterior.

Comentarios Informativos

A veces es útil proporcionar información básica con un comentario. Por ejemplo, considere este comentario que explica el valor de retorno de un método abstracto:

// Returns an instance of the Responder being tested.

protected abstract Responder responderInstance();

Un comentario como este a veces puede ser útil, pero es mejor usar el nombre de la función para transmitir la información cuando sea posible.

Por ejemplo, en este caso el comentario podría hacerse redundante renombrando la función: responderBeingTested.

Aquí hay un caso que es un poco mejor:

// format matched kk:mm:ss EEE, MMM dd, yyyy

Pattern timeMatcher = Pattern.compile(

“\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*”);

En este caso, el comentario nos permite saber que la expresión regular está pensada para coincidir con una fecha y hora que se formatearon con la función SimpleDateFormat.format utilizando la cadena de formato especificada. Sin embargo, podría haber sido mejor, y más claro, si hubiera cambiado a una clase especial que convirtiera los formatos de fechas y horas.