El estilo de programación se refiere a la forma de organizar y tabular el código fuente.
Como los archivos fuente (.cpp y .h) pueden ser modificados por muchas personas, es importante que los programadores compartan el mismo estilo de programación, generando así código fuente uniforme y fácil de entender.
Debe existir una referencia al dueño del Copyright (cada proyecto tiene un único dueño), el nombre del proyecto y la licencia utilizada. En la mayoría de los casos utilizamos GPL, con lo cual, cada archivo comienza con el siguiente comentario:
/* * Chanta Claus - Free 2D jump 'n run video game * Codename: chanta * * Copyright (c) 2004, 2005 Hugo Ruscitti * web site: http://www.losersjuegos.com.ar * * Chanta Claus is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * Chanta Claus is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */
Se utilizan tabulaciones para remarcar la presencia de un
bloque, utilizando -TAB-
en lugar de espacios, por
ejemplo:
int funcion (void) { // linea tabulada // segunda linea if (condicion) { // nuevo bloque tabulado // } }
Si quiere que las tabulaciones sean mas pequeñas altere la
configuración de su editor. En Vim se realiza con
set tabsize=n
, donde n
es el tamaño del
espaciado de la tabulación.
Si utiliza espacios no tendremos esta facilidad, la mayoría preferimos las tabulaciones de tamaño 8.
Los mensajes que se muestran al usuario deben estar en Inglés.
Mediante gettext se dará soporte al resto de los idiomas.
Si usted no cuenta con gettext en su equipo defina el archivo int.h con el siguiente contenido:
#define _(x) (x) #define N_(x) (x)
Luego, cuando quiera imprimir alguna cadena utilice printf:
prinf(_("error, can't load image %s\n"), path_image);
Evite el uso de cout, queremos que el orden de los parámetros se pueda modificar, algunos idiomas así lo requieren.
Los nombres de variables deben ser simples y claros, tienen que representar la lógica del dato contenido, por ejemplo:
float velocidad; int vidas; int puntos; class Pelota pelota;
Las funciones se escriben en minúscula y si contienen varias palabras se dividen con guiones bajos:
int iniciar (int resolucion, bool full_screen); void salir (void); void bucle_principal (void);
Las clases comienzan con Mayúsculas.
No utilice Notación Húngara, ni siquiera levemente anteponiendo una 'c' delante del identificador de una clase:
class Tile (en lugar de ctile) struct Player (en lugar de stplayer) char name[100] (en lugar de czname)
Las llaves en las funciones comienzan en el siguiente renglón, recuerde tabular el contenido del bloque:
void salir (void) { printf (_("Thanks for play this game\n")); printf (_("Shutdown system\n")); }
Este criterio es idéntico en el resto de los casos:
if (vidas < 1) { printf (_("game over\n")); salir (); } else { vidas --; print (_("lives %d\n"), vidas); }
No se deben exceder las 80 columnas de código, llegado el caso se debe modularizar aún mas el código.
Aunque existe una excepción: en algunos casos es inevitable
exceder el límite, si luego de varios intentos no puede
revertir esta situacion puede realizar un salto de linea
con \
y luego -ENTER-
.
int Mundo :: ejemplo (int codigo, ................., \ char * mensaje);
Para simplificar la lectura de las enumeraciones se deben ordenar en filas:
enum estados { PARADO, \ CORRIENDO, \ SALTANDO, \ CAMINANDO \ };
Para este caso es recomendable utilizar los valores de la enumeración en variables o parámetros de tipo "enum estado", en lugar de variables de tipo int. Así el compilador puede comparar los tipos de datos, en tiempo de compilación, y prevenir errores.
Luego de cada coma (,) debe agregar un espacio:
int reiniciar (int tipo, int energia, int vidas);
Los operadores también tienen que separarse con espacios:
for (i = 0; i < 10; i ++) printf ("i = %d\n", i);
Con excepcion de los siguientes:
. -> += -=
Cada función tiene que comenzar con un comentario que respete la siguiente regla:
/*! * \brief Descripción de la función en castellano * \author Nombre del autor * \return 1 en caso de error */ int imprimir (char *mensaje) { [...]
Las clases o estructuras se comentan de forma similar:
/*! * \brief Descripción de la tarea de la clase */ class player { private: void init (char *name, struct pos pos); [...]
Estos comentarios comenzados con (/*!) son procesados por el programa Doxygen para generar la documentación del proyecto.
El resto de los comentarios, internos a una función, no son necesarios. Cada función cumple una tarea muy especifica, no se deben explicar los cáculos internos de cada una.