Guía de estilo de programación en C++ estructurado

Guía de estilo de programación en C++
estructurado
Pequeños consejos sobre cómo escribir programas más legibles.

Índice
1Introducción........................................................................................................................................3
2Indicaciones generales........................................................................................................................3
3Identificadores....................................................................................................................................4
3.1Identificadores de estructuras.....................................................................................................4
3.2Identificadores de campos..........................................................................................................5
3.3Identificadores de registros.........................................................................................................5
3.4Identificadores de funciones.......................................................................................................5
3.5Identificadores de variables locales en funciones.......................................................................5
3.6Ejemplo con estructuras, variables y funciones..........................................................................6
3.7Declaración de variables.............................................................................................................7
4Comentarios........................................................................................................................................8
4.1Comentarios de inicio de bloque................................................................................................8
4.2Comentarios aclaratorios............................................................................................................8
4.3Comentarios sobre funciones y procedimientos.........................................................................8
5Disposición de elementos.................................................................................................................10
5.1Estructuras................................................................................................................................10
5.1.1Unidades de traducción.....................................................................................................10
5.2Funciones..................................................................................................................................11
5.2.1Estructuras de decisión y repetición..................................................................................12
5.2.1.1Cuerpos de instrucciones de una sola línea...............................................................12
5.3Espaciado..................................................................................................................................13

1 Introducción
En este documento se explica brevemente, y con ejemplos, cómo escribir programas más legibles.
A lo largo de su vida profesional, cualquier programador se plantea la pregunta de cómo escribir sus
programas de manera que sean más legibles, y por tanto que puedan ser mantenidos (corrección de
errores, ampliación de funcionalidad) con facilidad, tanto por él mismo como por otros
programadores (una situación típica en cualquier empresa).
Dado que la misma situación en cuanto a legibilidad de código suele ser resuelta por
distintos programadores de la misma forma, pero con distintos matices de diferenciación, es
interesante seguir una guía de estilo que nos explique como otros resolvieron ese mismo problema,
hasta que dicha solución se convirtió en un estándar.
2 Indicaciones generales
El propósito de seguir una norma de estilo es hacer que el código fuente de un programa sea tan
legible como sea posible. Así, hay tres puntos básicos que se deben cuidar: el espaciado horizontal,
el espaciado vertical y la indentación. El espaciado horizontal consiste en que las líneas en las que
esté dividido el código fuente deben ser de una longitud máxima lo más próxima posible a 80
caracteres, ya que al imprimir el código en papel cualquier línea superior a 80 columnas se descarta
automáticamente.
Uno de los problemas que se puede encontrar al codificar es la manera más correcta para
dividir una línea muy larga. Respuestas comunes a esta pregunta son: antes de una subexpresión,
antes de un operador, o antes de un paréntesis. Por ejemplo:
int x = ( (a * b + c ) / ( c * d * d ) )
+ ( a / ( b * c ) )
+ ( ( 3.1451927 * b ) + d )
;
Los operadores deben separarse mediante espacios para mayor claridad, a excepción hecha
de operadores unarios como el incremento o decremento, tanto postfijo como prefijo, que suelen
colocarse pegados al operando al que modifican (lo más típico, por claridad), pero también pueden
colocarse espaciados, a elección del programador.
int x = ++ i;
int y = j++ + ++ x;
El espaciado vertical consiste en cuántas líneas ocupa una función o una estructura, en el
código fuente. En general, es útil autoimponerse un límite de una hoja por cada función o
procedimiento. Es extraño, siempre que la misma no consista en multitud de acciones repetitivas
(como escribir en un archivo), que una función bien diseñada ocupe más allá de un folio. En caso
contrario, será conveniente considerar que posiblemente sea interesante subdividirlo en varias
subfunciones (probablemente de acceso privado).
Además, en el espaciado vertical intervienen las llaves que se emplean para marcar el
comienzo y fin del cuerpo de una función, de un bucle, ... cada una de esas llaves puede llegar a
consumir una línea por sí sola, incluso dos. Así, para salvar algo de espacio vertical, se suelen
mantener las llaves de apertura y cierre, cada una en una línea, para el cuerpo de las funciones, y en
cambio colocar la llave de apertura en la misma línea para bucles y estructuras de decisión. Por
ejemplo:

int dividir(int a, int b)
{
if ( b != 0 ) {
return a / b;
}
}
return 0;
... (recuérdese que en un programa real será mucho más adecuado responder a la
contingencia que supone dividir un número entre cero, que responder con cero “silenciosamente”,
lo cual supone un error no detectado).
La indentación es vital para poder comprender rápidamente los elementos funcionales de un
programa. Así, el cuerpo (las instrucciones) de una función o procedimiento debe estar alineado en
su margen izquierdo más a la derecha que su cabecera, de la misma forma que un bucle dentro de
esa función y así sucesivamente. Por ejemplo:
int elevarA(int x, int y)
{
int toret = 1;
}
if ( y >= 0 ) {
for(; y > 0; --y) {
toret *= x;
}
} else toret = 0
return toret;
3 Identificadores
Los identificadores se utilizan en varias (innumerables) ocasiones en programación: enumeraciones,
funciones, constantes, variables locales ..., y son claves para entender qué valores puede contener
una variable, qué hace una función o a qué valores representa un enumerado. Por eso, hay que poner
especial cuidado en su elección. También será interesante seguir unas pequeñas reglas a la hora de
escribir un identificador que hagan que a su vez podamos obtener el máximo significado del mismo
si se está leyendo en un listado.
En general, los identificadores deben ser tan cortos como sea posible, pero a la vez tan
informativos como sea posible. Muchas veces, además, es imposible utilizar un solo sustantivo para
nombrar una variable, función o estructura; en ese caso, se concatenarán todos para formar el
identificador final, poniendo cada inicial en mayúscula. Si bien algunos lenguajes modernos lo
permiten (como Java), a través del soporte unicode, evítense los acentos, las diéresis ... en los
identificadores.
3.1 Identificadores de estructuras
Los identificadores de estructuras deberían corresponderse con sustantivos de la vida real o del
concepto que se está modelando con el programa. Así, identificadores de estructuras típicos pueden
ser: Casa, Coche, Barco, Cuenta ...
El identificador de la estructura, en caso de estar compuesto por más de una palabra, se
construye concatenando todas las palabras, y poniendo la inicial de cada una de estas palabras en
mayúsculas. Por ejemplo: CuentaCorriente, CuentaCredito ...

struct Rectangulo {
// más cosas ...
};
struct CuentaCorriente {
// más cosas ...
};
3.2 Identificadores de campos
Los identificadores de campos (o datos miembro), siguen las mismas normas que los de las
estructuras, pero con la primera inicial en minúscula. Así, por ejemplo, identificadores válidos son
identificadorCompleto, precioEuros, ...
struct CuentaCorriente {
double saldoEuros;
};
3.3 Identificadores de registros
Los identificadores de registros (o variables de las estructuras) siguen las mismas reglas que los
identificadores de los campos.
3.4 Identificadores de funciones
Los identificadores de funciones siguen las mismas reglas que para campos y registros. Sin
embargo, deben escogerse de modo que sugieran de manera intuitiva qué hacen. Así, el
identificador debe ser un verbo o al menos contener uno. Las funciones que devuelven un valor
lógico deberían tener un verbo copulativo (ser o estar) al comienzo del identificador.
double calculaArea(Triangulo);
int esPalindromo(const char *);
Evítensen identificadores como los siguientes:
int procesar(CuentaCorriente c); // Mal: identificador no intuitivo
void pasoAuxiliar(Rectagulo r); // Mal: identificador simplemente erróneo
void procesaYCuenta(); // Mal: Dividir en dos funciones
Cuando un identificador contiene una conjunción como y, es signo inequívoco de que la
función que nombra realiza más de una tarea y debe ser por tanto separada en dos funciones
separadas.
Los mejores identificadores son aquellos que describen con un identificador más corto lo
que hace la función. Además, es interesante seguir ciertas pautas: en el caso de funciones que
devuelven un booleano (un valor verdadero o falso), es interesante nombrarlos con un prefijo
formado por los verbos ser o estar, como:
esPalindromo(const char s[]);
esPar(int);
fueModificada(const CuentaCorriente c);
3.5 Identificadores de variables locales en funciones
En el caso de variables locales de funciones, existen varias particularidades. Por ejemplo, a las
variables locales empleadas en bucles se les suele asignar identificadores de una letra tipo 'i' y 'j',
también en el caso de algunos argumentos simples (si bien este caso es mejor, sin embargo, evitarlo,

cuando sea posible, y asignar identificadores descriptivos) de funciones.
void cnvtMayusculas(char s[])
{
int i = 0;
}
for(; s[ i ] != 0; ++i) {
s[ i ] = toupper( s[ i ] );
}
Los identificadores de variables también pueden informar sobre para qué se utiliza esa
variable, y no restringirse a tan solo información sobre qué valores alberga. Por ejemplo, en el
código siguiente toret (a retornar) es una variable que se utiliza en todas las funciones para devolver
un valor.
int calcularLongitud(const char s[])
{
int toret = 0;
}
for(; s[ toret ] != 0; ++toret) {
}
return toret;
3.6 Ejemplo con estructuras, variables y funciones
A continuación, se muestra un ejemplo completo:
#include
const double PI = 3.1415927;
struct Circulo {
double radio;
double perimetro;
double area;
};
void calcularDatos(const Circulo &c)
/* Completar la estructura círculo con los datos adecuados */
{
c.area = c.radio * c.radio * PI;
c.perimetro = 2 * PI * c.radio;
}
int main(void)
{
Circulo miCirculo;
}
printf( “Introduzca el radio del círculo: “ );
scanf( “%f”, &miCirculo.radio );
calcularDatos( miCirculo );
printf( “Círculo de radio: %f\n\tÁrea: %f\n\tPerímetro: %f\n”,
miCirculo.radio,
miCirculo.area,
miCirculo.perimetro
);

3.7 Declaración de variables
Se debe colocar cada variable en una línea, incluso siendo del mismo tipo.
int x, y; // Es necesaria una segunda mirada para fijarse en 'y'
int main()
{
int x;
int y;
char c;
char toret[128];
}
// más cosas ...
return 0;
C permite minimizar muchísimo ciertas expresiones. Por ejemplo, el siguiente bucle copiaría
una cadena de caracteres de C (un vector de char), en otra de destino:
void copiaCadena(char cadDestino[], const char cadOrigen[])
{
int i = 0;
while( cadDestino[ i ] = cadOrigen[ i++ ] );
}
Esto es bueno en cuanto a espaciado vertical, desde luego, pero debe valorarse cuándo el
ahorro de espaciado merma la legibilidad del código.
void copiaCadena(char cadDestino[], const char cadOrigen[])
{
int i = 0;
for(; cadOrigen[ i ] != 0; ++i) {
cadDestino[ i ] = cadOrigen[ i ];
}
}
La anterior función realiza la misma tarea que la predecesora. Sin embargo, está
perfectamente claro cuándo el bucle termina (al llegar a la marca de fin de cadena de la cadena de
origen), cuándo se hace explícitamente una copia y también cuándo, después, se incrementan ambos
contadores. Es una función que se puede comprender de un vistazo, mientras que la anterior, aún
para un programador con experiencia, supondrá invertir unos cuantos segundos. Finalmente, la
calidad del código máquina generada es la misma en ambos casos, si bien es cierto que el primer
ejemplo podría generar, según el compilador, un número de instrucciones máquina algo menor.
4 Comentarios
Un comentario debe ser siempre clarificador, útil, y, en cambio, cuanto más corto mejor. En
particular, debe cuidarse en no insultar la inteligencia del lector en determinadas ocasiones,
comentando secuencias de código obvias y desesperarlo al encontrarse con construcciones
complejas que no tienen ningún comentario.

int areaRectangulo = lado1 * lado2; // calcula área
areaCirculo = PI * r * r; // calcula área del círculo
// PI es 3.1415927
En el contexto del ejemplo anterior, el tercer comentario es absolutamente innecesario,
mientras que los dos primeros son cuestionables, siempre que los identificadores hayan sido
escogidos cuidadosamente, como es el caso.
4.1 Comentarios de inicio de bloque
Existen dos tipos básicos de comentarios, los que podríamos denominar comentarios encima, y los
que podríamos denominar comentarios a la derecha. Los más recomendables son los primeros,
pues suelen explicar un bloque de código, a modo de párrafo, aclarando mucho la lectura.
void listarPersonas(char buffer[], const Persona &vp[MaxPersonas])
/**
@param buffer vector de caracteres para listado
@param vp vector de personas a listar
*/
{
*buffer = 0;
int i = 0;
}
// Obtener los nombres de cada persona
for(; i < MaxPersonas; ++i) {
strcat( buffer, vp[ i ].nombre );
strcat( buffer, “\n” );
}
return buffer;
Como puede observarse, el comentario de la función sigue un formato específico, que se discutirá
en las siguientes secciones.
4.2 Comentarios aclaratorios
Los comentarios a la derecha deben emplearse como mensajes aclaratorios, intentando mantener
especialmente en ellos la concisión, pues es fácil que se alcancen rápidamente más de ochenta
caracteres en esa línea. Agravando aún más este último problema, deben colocarse alejados del
código que aclaran para que sean visibles.
// Cálculos previos al rendering
areaRectangulo = lado1 * lado2; // en cms
4.3 Comentarios sobre funciones y procedimientos
Desde la llegada del lenguaje Java, y su herramienta de documentación, Javadoc, se han
generalizado los comentarios formateados con un determinado estilo, y aceptando unos
determinados parámetros de documentación embebidos en ellos. Para el lenguaje C, existe también
un equivalente a Javadoc, la herramienta Doxygen 1 , de gran aceptación.
Así, cuando un comentario, en lugar de empezar por /*, comienza por /**, al pasar el código
por la herramienta Doxygen, ésta genera la documentación recogida en varios formatos (incluyendo
el HTML, que lo hace ideal para las referencias cruzadas). Estos comentarios también son útiles al
desnudo, por lo que deben colocarse en las cabeceras (los ficheros con extensión .h, donde se
1 Doxygen puede encontrarse en: http://www.doxygen.org

declaran las clases; consúltese la sección sobre unidades de traducción), inmediatamente antes de
cada estructura, función, o campo. Son las cabeceras las que serán consultadas por el programador
que utilice el módulo para conocer su interfaz pública.
// rectangulo.h
/**
La estructura que representa a los rectángulos
*/
struct Rectangulo {
/// La información sobre la base del rectángulo
double base;
/// La información sobre la altura del rectángulo
double altura;
};
/**
* Creador de rectángulos
* @param b La base del futuro rectángulo
* @param a La altura del futuro rectángulo
*/
Rectangulo creaRectangulo(double b, double a);
/**
* Calcula el área del rectángulo
* @return El área del rectángulo, según sus lados
*/
double calcularArea(const Rectangulo &r);
// rectangulo.cpp
/*
Implementación del TDA rectángulo.
*/
#include “rectangulo.h”
Rectangulo creaRectangulo(double b, double a)
{
Rectangulo toret;
toret.base = b;
toret.altura = a;
return toret;
}
double calcularArea(const Rectangulo &r)
{
return ( r.base * r.altura );
}
De los parámetros que se pueden utilizar en este tipo de comentarios, destacan @param y
@return. El primero sirve para documentar un parámetro de una función o procedimiento, tal y
como se ve en la función crearRectángulo() del módulo Rectángulo de ejemplo, más arriba. El
segundo sirve para documentar el valor de retorno de una función, tal y como se aprecia en la
función calcularArea() del módulo del mismo ejemplo. Por último, con @see es posible hacer
referencias cruzadas entre funciones y estructuras de datos, por ejemplo.

5 Disposición de elementos
5.1 Estructuras
Al igual que al tratar con variables locales, deben colocarse los miembtos de una estructura uno en
cada línea. Debe aprovecharse para documentar adecuadamente la entidad. Si el significado de los
miembros no es obvio, entonces, deben añadirse comentarios para cada campo.
/// Estructura que representa a puntos de dos dimensiones
struct Punto {
double x;
double y;
};
5.1.1 Unidades de traducción
En terminología C, el compilador traduce a código máquina unidades de traducción, que son
ficheros con extensión .cpp, también conocidos como ficheros de implementación, ya que en ellos
se definen las funciones y variables globales. Estos ficheros normalmente tienen asociados unos
ficheros de cabecera (con extensión .h), donde se declaran los miembros públicos. Es muy
importante la disposición de los prototipos de las funciones públicas y las declaraciones de las
estructuras públicas en las cabeceras, mientras que las respectivas implementaciones deben aparecer
en los ficheros de implementación.
/* punto.h */
#ifndef _PUNTO_H_
#define _PUNTO_H_
/** Estructura que representa a puntos de dos dimensiones **/
struct Punto {
double x;
double y;
};
/** Origen de coordenadas **/
extern const Punto puntoOrigen;
/** Creador de registros Punto
* @param a La coordenada horizontal
* @param b La coordenada vertical
*/
Punto crearPunto(double a, double b);
/// @return la coordenada horizontal
double calculaDistancia(const Punto &p1, const Punto &p2);
#endif
/* punto.cpp */
#include “punto.h”
#include
const Punto PuntoOrigen = { 0, 0 };
static double calculaDistanciaOrigen(const Punto &p1)
/** Calcula distancia a origen – Privada **/
{
return sqrt( ( p1.x * p1.x ) + ( p1.y * p1.y) );
}

inline Punto crearPunto(double a, double b)
{
Punto p = { a, b };
return p;
}
double calculaDistancia(const Punto &p1, const Punto &p2)
{
return abs( calculaDistanciaOrigen( p1 )
– calculaDistanciaOrigen( p2 ) )
;
}
La línea #ifndef _PUNTO_H_ y la siguiente lo que hacen es evitar que se compile la cabecera
punto.h más de una vez. Ésto puede suceder inadvertidamente en un proyecto complejo, cuando
más de una cabecera incluye la primera. El diagnóstico de este problema es sencillo, pues en ese
caso el compilador se quejaría de una redeclaración del módulo Punto.
Nótese que se ha incluido un objeto constante. Para poder ser utilizado debe ser declarado
en el fichero de cabecera, con extern, si bien nunca definido (la cabecera puede ser incluida en
varias unidades de traducción: poner la definición en la cabecera significaría que todas ellas
tendrían un objeto puntoOrigen distinto, aunque con el mismo identificador, lo que provocaría un
error de enlace). La definición, como puede verse, aparece en el fichero de implementación,
mientras que en el fichero de cabecera aparece una declaración con extern, de manera que el
compilador sepa que está definida en algún módulo (pero sólo en uno, claro, en otro caso se
produce otro error).
Si, en cambio, se desea que un objeto no sea público, debe omitirse cualquier mención sobre
él en la cabecera, y en el momento de la definición en el archivo de implementación debe añadirse
el modificador static (que en este caso de aplicación significa privado, y no tiene, explícitamente,
el mismo significado que cuando se aplica a una variable local de una función).
5.2 Funciones
En las funciones, se debe adoptar como esquema básico la típica estructura inicializacióndesarrollo­limpieza,
es decir el comienzo de la tarea, inicializando (y creando, cuando sea oportuno)
las variables necesarias, el desarrollo del problema, como el bucle del ejemplo situado más abajo,y
finalmente, cuando es necesario, la limpieza de los recursos utilizados.
int sumaFicheroDatos(const char nombreFichero[])
/**
Lee el contenido de un archivo de texto, en el que cada línea es un
número entero, y lo suma.
@param nombreFichero El nombre de fichero a cargar
@return La suma de todos los valores en el fichero.
**/
{
int num;
int toret = 0;
FILE * f = fopen( nombreFichero, “rt” );
if ( f != NULL ) {
fscanf( f, “%d\n”, &num );
while( !feof( f ) ) {
toret += num;
fscanf( f, “%d\n”, &num );
}
fclose( f );

}
}
return toret;
5.2.1 Estructuras de decisión y repetición
Es típico encontrarse con la necesidad de tener que crear estructuras condicionales (if) o de
repetición (while), que se refieren a condiciones complejas. Debe tratarse, en estos casos, de
disponer una subcondición por línea, comenzando por el juntor (and (&&), or(||), y not(!)). Si es
necesario, una subcondición puede llevar un comentario "a la derecha". Si existen varias
subexpresiones condicionales, se deben indentar respecto a la expresión principal.
if ( buffer != NULL
&& feof( f )
&& tamMaxBufferDestino > 0 )
{
while( !feof( f ) ) {
/* más cosas ... */
}
}
if ( feof( f )
&& bytesLeidos > 0 )
{
memcpy( dest, buffer, tamMaxBufferDestino );
}
Cuando se crean estructuras de decisión con más de una expresión condicional, no se debe
utilizar la posibilidad de crear los cuerpos de instrucciones de una sola línea sin las llaves de inicio
y fin de bloque ( { y } ), ya que la sentencia no sería visible, como se muestra a continuación.
if ( feof( f )
&& bytesLeidos > 0 )
f.close();
5.2.1.1 Cuerpos de instrucciones de una sola línea
En general, es más legible evitar esta posibilidad. Las sentencias de un bloque sin llaves casi pasan
desapercibidas, y por tanto es mejor cambiarlas por bloques siempre que sea posible. Recuérdese
que los bloques de una sola línea sin llaves de comienzo y fin son una posibilidad, no una
obligación. En cuanto al espacio vertical, colocar la llave inicio en la misma línea de una sentencia
de repetición o de decisión (siempre que no haya múltiples subexpresiones condicionales), es una
medida que puede ser muy útil.
En el caso de una sentencia if­then­else con sólo una expresión condicional, se puede utilizar
la posibilidad de los bloques sin llaves de comienzo y fin, por ejemplo:
int buscarPersona(const char nombre[], const Persona &vp[MaxPersonas])
/**
@param nombre vector de caracteres con el nombre a buscar
@param vp vector de personas donde buscar
@return
*/
{
int i = 0;
// Buscar en el nombre de cada persona
for(; i < MaxPersonas; ++i) {
if ( vp[ i ].nombre == nombre ) {
break;

}
}
5.3 Espaciado
}
if ( i < MaxPersonas )
return i;
else return -1;
El espaciado se refiere a separar ciertos elementos (operadores y paréntesis, principalmente), de los
argumentos para que el conjunto sea más legible. El uso típico consiste en separar con un espacio
los argumentos en las listas de parámetros formales y de argumentos, los corchetes del operador de
subíndice, y los operadores como =, *. /, + y ­. Por ejemplo, compárense las siguientes muestras:
int x=a+b;
int x = a + b;
numRegistros=v.size()+registrosCabecera[i];
numRegistros = v.size() + registrosCabecera[ i ];
int z=elevarA(x,y);
int z = elevarA( x, y );