[C con Clase] Cheat Sheet de buenas constumbres para programar en C++

Mar Feb 5 18:02:03 CET 2013

Buenos días.

He de reconocer que soy un adicto a los Cheat sheet cuando tengo que manejar una librería o programa. Por ejemplo openCV o VIM (Buscad en google si no sabeis a lo que me refiero). Una cosa que he echado de menos en C++ con clase (O al menos no he encontrado) es una hoja por las 2 caras con una serie de convenciones para programar en grupos de varias personas y no morir en el intento.

Cada uno tiene sus manías, pero me parece importante, cuando trabajas con otras personas, tener una serie de estándares que seguir para que el código sea lo más homogéneo y limpio posible. He empezado a crear una Cheat Sheet lo más básica posible, estoy intentando conseguir más protocolos o normas, pero quiero hacerla lo más sencilla posible y escribirla en Látex.

Si teneis buenas costumbres y quereis compartirlas estoy abierto a sugerencias.

De momento este es el borrador que tengo preparado:

------------------------------------------------------------------------------------------------------------------------------------------------

Cheat Sheet Programmers

Remember:
Code should be locally coherent
	and single-functioned: One function should do exactly one thing. It
	should be clear about what it's doing. 

	Local code should explain, or at
	least hint at the overall system design. 

	Code should be self-documenting. Comments should be avoided
	whenever possible. Comments duplicate work when both writing and
	reading code. If you need to comment something to make it
	understandable it should probably be rewritten. 

Palabras clave:
- TODO: Código que necesita mejora
- FIXME: Indica fragmento de código
con bug
- WORKAROUND: Arreglando bug en la zona
para evitar conflictos

Files
- .h: Headers
- .cpp: Source
- .hpp: Template

Variables:
- Prefijo: m_ si son variables miembro.
- Nombre descriptivo: Para saber que
hace sin necesidad de comentario.
- Usar Mayúsculas cada nueva palabra.

Ejemplo: m_ContadorVisitas

Directorios: 

- trunk: Línea general de desarrollo.
Siempre debe compilar
- branches: Copias del trunk para
experimentos o cambios importantes
- tag: Versiones estables
- resources: Guardar todo archivo común
a todas las líneas de desarrollo. Por ejemplo modelos 3D o imagenes.
- 3rdParty: Todas las dependencias
externas.

Compilación:
- Script general multiplataforma
- Variables de entorno en script y no
ordenador. Usa un CMAKE que pida esos datos.
- Referencias relativas dentro del
proyecto con las variables dadas a CMAKE

Includes:
Todo
include debe usar <chevron_brackets>
Usa
“Comillas” solo si el include está en el mismo directorio.

Clases:
-
Los nombres empiezan siempre por mayúscula.
P.E:
class MyNuevaClase;

Constantes:

-
Toda constante siempre en mayúsculas.
P.E:
const static int SIZE_HEIGHT = 1024;

Paréntesis:

-
Siempre en una línea nueva

P.E:

if (a < b)
{
  ...
}
else
{
  ...
}

Macros:
Toda
macro siempre TODO_MAYUSCULAS_CON_BARRABAJA

#ifndef GAMEMANAGER_H_
#define VERSION 0.0

// the code

#endif // GAMEMANAGER_H_

Defines:

Convenciones:
- Multiplataforma: Trata de seguir los
estándares de programación.
- Const: Usa constantes para variables
y funciones siempre que puedas. 

- Minimiza los comentarios: Los nombres
descriptivos de por si no hace falta explicarlos. Las tareas
complejas si.
- Tabulación y espaciado: Emplea un
espaciado coherente.
- Usa siempre llaves en una línea
nueva
- Encapsulado I: Devuelve referencias y
no punteros.
- Encapsulado II: Usa variables
privadas, usa getters y setters para ver/editar las accesibles.

Debuging Android:
#include <android/log.h>
#define  LOG_TAG    "foo"
#define  LOGI(...)  __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__)

Patrones de diseño:
Utilizalos solo cuando sea necesario.
- Singleton: Cuando sea una estructura
general que necesite ser accedida desde cualquier punto y siempre
este en memoria.
- Factory: Construcción de clases
usando una serie de métodos predefinidos
- Facade: Reducción de complejidad
usando una serie de módulos y protección contra ingeniería
inversa.
Documentar para Doxygen:
H
- Versión resumida de cada explicación
para que sea usada desde el exterior.
CPP
- Comenta cada función usando:
/**
 *
 */
- Añade los campos que necesites.
Obligatorio brief , params y una pequeña descripción.
- /brief Titulo o breve resumen de la
función
- Descripción
- /param[in] Un parámetro de entrada
por línea
- /param[out] Un parámetro de salida
por línea.
- /author Solo 1 por clase
- /bug Si tiene un bug la función
especificar
- /version Version de la función
- /warning Indicar si hay que tener
cuidado, por ejemplo si será deprecated.
- /see Referencia a algo importante
- /image Para añadir una imagen

Dependencias:
- Especifica que librerías necesitas y
su versión en un README.txt

------------------------------------------------------------------------------------------------------------------------------------------------------------------

Recursos recomendables:
Usar Patrones de diseño:
http://en.wikibooks.org/wiki/C%2B%2B_Programming/Code/Design_Patterns
Usar STL:
http://www.sgi.com/tech/stl/table_of_contents.html
Libros de C++ a tener en cuenta:
Effective C++ , More Effective C++, Effective STL de Scott Meyers.
Otros:
http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code

------------------------------------------------------------------------------------------------------------------------------------------------------------------

Cualquier comentario es bienvenido.

Un saludo.

------------ próxima parte ------------
Se ha borrado un adjunto en formato HTML...
URL: <http://listas.conclase.net/pipermail/cconclase_listas.conclase.net/attachments/20130205/780631d8/attachment.html>