Etiqueta para programadores

Recuerdo que en la universidad existía un curso electivo de "Protocolo", donde te instruían en las buenas maneras en el comer y el actuar. La evaluación final era asistir a una cena de gala en una embajada y no hacer quedar mal a la profesora xD .

Citando a Frieda Holler, la etiqueta tiene que ver bastante con el respeto,  y saber como comportarse demuestra consideración con los demás. Y así como es necesario ser educado a la hora de comer, hay que saber también ser correcto al momento de programar. Codificar de manera ordenada y clara es una muestra de respeto hacia el programador que va a dar mantenimiento a lo que has construido. No indentar, por ejemplo, puede ser considerado una malcriadez.

Ningún profesor en la universidad me mencionó que existían convenciones de programación, así que en mis primeros años era bastante salvaje al codificar. Cuando entré a trabajar, el código desordenado -pero funcional- que en la universidad me hubiera valido un 20 era devuelto por el área de Arquitectura indicándome que indente, que comente y que siga los estándares. De rechazo en rechazo fui ordenándome de a pocos y ahora ya guardo ciertas formas con el código fuente.

El listado a continuación es un extracto de Java Code Conventions, que siendo publicado por Sun Microsystems puede considerarse oficial. Ojalá les sea de ayuda, y les sugiero programen siempre pensando en el desarrollador que va  a dar mantenimiento a su código (de modo que no te eche maldiciones xD). Dicho esto, comenzamos:

•  Los archivos Java con más de 2000 líneas -incluyendo líneas en blanco y comentarios- deben evitarse.
•  Las primeras líneas de un archivo Java deben contener comentarios de entrada, de preferencia en este formato:

/*
 * Nombre de clase
*
 * Versión
 *
 * Aviso de Copyright
 */

•  Dentro de una clase las primeras variables en declararse son las variables de clase (estáticas) y luego las variables de instancia. Dentro de cada categoría, primero deben colocarse las variables públicas, luego las protegidas y por último las privadas.
•  Un archivo Java debe tener la siguiente estructura:

1. Documentación de clase/interfaz
2. Declaración de clase
3. Variables de clase
4. Variables de instancia
5. Constructores
6. Métodos

• Una línea de código no debe exceder de 80 caracteres. Las líneas que excedan esta longitud pueden dividirse de esta manera:

function(longExpression1, longExpression2, longExpression3,
         longExpression4, longExpression5);

En la caso de sentencias condicionales:

if ((condition1 && condition2)
        || (condition3 && condition4)
        ||!(condition5 && condition6)) {
    doSomethingAboutIt();
}

Y para sentencias ternarias:

alpha = (aLongBooleanExpression) ? beta
                                 : gamma;

• Los comentarios deben utilizarse para brindar información adicional que no está explícita en el código fuente.
• Los comentarios no deben estar delimitados en cajas hechas de asteriscos u otros caracteres.
• Los comentarios en bloque deben usar al inicio de cada archivo java y antes de cada método. Un comentario en bloque debe estar separado del resto del código por una línea en blanco. Todas las líneas de un comentario en bloque comienzan con un asterisco (*). Por ejemplo:

/*
 * Este es un comentario en bloque
 */

• Se pueden usar comentarios cortos de uno línea indentados al mismo nivel del código fuente. Si el comentario no puede estar contenido en una sóla línea, debe utilizarse el formato de comentarios en bloque. Un comentario de una línea debe estar precedido de una línea en blanco. Así:

if (condition) {
    /* Acciones para la condición */
    ...
}

• Los comentarios de documentación describen clases Java, interfaces, constructores, métodos y atributos. Cada comentario de documentación se encuentra delimitado por /** ...*/, y debe aparecer justo antes de la declaración:

/**
 * La clase Example provee...
 */
class Example { ...

• Los comentarios de documentación no deben colocarse dentro de un método o una definición de constructor, dado que Java asocia los comentarios de documentación a la primera documentación después del comentario.
• Se recomienda utilizar una declaración por línea. Entonces, es preferible utilizar esto:

int level; // nivel de indentación
int size;  // tamaño de la mesa

que esto:

int level, size;

• Colocar las declaraciones sólamente al inicio de los bloques (un bloque está limitado por llaves). No se debe esperar a declarar las variables justo antes de utilizarlas. Así:

void MyMethod() {
    int int1;         // inicio del bloque del método
    if (condition) {
        int int2;     // inicio del bloque "if"
        ...
    }
}

• Tratar siempre de inicializar las variables locales al momento de declararlas.
• Utilizar siempre llaves para sentencias condicionales (if). Evitar este formato:

if (condition) //EVITAR!! UTILIZAR LLAVES!
statement;

• Cada sentencia switch debe incluir la condición default. Dentro de default, utilizar break es redundante pero evita errores en caso se agreguen nuevas condiciones. Cuando no se requiera incluir break en un case, agregar el comentario /* falls through */:

switch (condition) {
case ABC:
statements;
    /* falls through */
case DEF:
statements;
    break;
case XYZ:
statements;
    break;
default:
statements;
    break;
}

• Los nombre de clase debe ser sustantivos, donde la primera letra de cada palabra interna comience con mayúsculas. Utilizar palabras completas y evitar acrónimos y abreviaturas:

class Raster;
class ImageSprite;

• Los nombres de los métodos debe ser verbos, la primera letra del nombre del método debe estar en minúsculas. La primera letra de cada palabra interna debe estar en mayúsculas:

run();
runFast();
getBackground();

• Las variables declaradas como constantes deben tener nombres en mayúscula, y las palabras internas deben estar separadas por guiones bajos (_). Así:

int MIN_WIDTH = 4;
int MAX_WIDTH = 999;
int GET_THE_CPU = 1;

• No hacer las variables de instacia y de clase públicas a menos que se tenga una buena razón.
• Evitar hacer referencia a variables o métodos de clase desde objetos. Usar para esto el nombre de la clase.

classMethod();             //OK
AClass.classMethod();      //OK
anObject.classMethod();    //EVITAR!