Mi nomenclatura de codificación

Con el paso del tiempo, uno se va dando cuenta de lo conveniente que es la aplicación de ciertas prácticas, que empíricamente se ha demostrado que funcionan.

En el mundo de la programación, hay infinidad de problemas que nos han enseñado algo concreto. La forma en que los solucionamos pasa a partir de ese momento a ser parte de nuestra caja de herramientas particular, y es probablemente el activo más valioso que poseemos los que vivimos de la tecnología.

En concreto, las convenciones que usamos a la hora de escribir código son importantes. El siguiente texto, está extraído de la documentación interna que escribí para la realización de un juego de rol basado en turnos por internet, que lamentablemente nunca llegó a ver la luz. A su vez, esa versión se basó en otros documentos que había escrito estando involucrado en diferentes proyectos para diferentes empresas.

Su coherencia está sobradamente probada, pues ha sido utilizada por varias personas durante más de 8 años. En efecto ha ido sufriendo evoluciones, pero la esencia jamás ha cambiado.

Consideraciones generales
– Los archivos independientemente de su lenguaje se escribirán indentando con tabuladores configurados a 4 espacios.
– Los nombres de variables, constantes, controles, … serán en inglés, así como todos los comentarios de las aplicaciones.
– Los objetos una vez liberados, serán asignados a NULL, y al crearse estáticamente se inicializarán a NULL también.
– Si el lenguaje lo permite trabajaremos orientados a objetos, y teniendo en cuenta que es más importante la estabilidad que la velocidad de ejecución. Más importante la mantenibilidad que el desarrollo rápido.

Estos son ejemplos a seguir:

Para C/C++

// ---------------------------------------------------------------------
AnsiString __fastcall GetNombre (const AnsiString psName)
{
	AnsiString sName=””;

	psName=sName;
	if (sName==””)
	{
		sName=”Sin nombre”;
	}
	return(sName);
}
// ---------------------------------------------------------------------

Para PHP

// ---------------------------------------------------------------------
function GetNombre ($psName)
{
	$sName=””;

	$psName=$sName;
	if (empty($sName))
	{
		$sName=”Sin nombre”;
	}
	return($sName);
}
// ---------------------------------------------------------------------

Para SQL

# ---------------------------------------------------------------------
INSERT INTO
	tbl_banner 
	(id_banner, 
	str_image, 
	str_url, 
	str_hint, 
	int_cents) 
VALUES
	(1, 
	'http://impes.tradedoubler.com/imp/img/36434/767754',
	'http://tracker.tradedoubler.com/click?p=4908&a=767754&g=36434',
	'Air France',
	'5');
# ---------------------------------------------------------------------

Nombre de constantes y variables
Empiezan con un literal del ámbito de la variable, un literal de array, un literal del tipo de información y el nombre de la variable.

Ámbitos
Constante	K
Global de la aplicación	g
Privada del módulo	m
Parámetro de método/función	p
Local

Tipos
Booleano	b
Carácter	c
Clase	cls
Doble	d
Entero	i
Entero largo	l
Flotante	f
Instancia	o
Puntero	p
String	s
Sencillo	n
Variant	v
Button	but
Checkbox	chk
Form	frm
Frame/Panel	fra
Image	img
Label	lbl
Memo	mmo
Progressbar	pgb
Radio/Option	opt
Statusbar	stb
Textbox/Edit	txt
…	…

Ejemplos:
– sValue: String local llamado Value.
– mvReturn: Variant de modulo llamado Return.
– gacBuffer: Array de caracteres global llamado Buffer.
– KI_MAX_SIZE: Constante entera llamada MAX_SIZE.

Conclusiones
Las convenciones a la hora de escribir código, están condicionadas por el historial de programación de la persona que las utiliza, en mi caso como es fácil deducir, es el Basic.

No tiene mayor importancia que se siga esta nomenclatura, o cualquier otra; en cambio si que es importante ceñirse a un convenio propio, que sea cuanto más estricto mejor.

Si está basado en notación húngara, es un punto a favor. Otro condicionante importante es acotar las estructuras de control, a pesar de que en algunos casos no sea necesario. Esto ayuda a evitar errores de edición ulterior. Sería el caso del los if de C/C++, cuando solamente alojan una sentencia. Finalmente, es importantísimo indentar con tabuladores.

El resto de normas, son modificables según el gusto personal de cada uno: el lugar donde colocamos los acotadores de estructuras de control, si separamos con espacios antes o después de símbolos, la forma de separar las funciones, …

El uso correcto de una buena nomenclatura, facilita la edición de código por parte de terceros. Aunque el convenio utilizado no se parezca en absoluto al propio, si es coherente, y aplicado sin excepciones, tras 10 minutos de revisión de los fuentes, nos sentiremos totalmente cómodos con él.

Un aspecto más complejo, que no es posible formalizar a través de reglas, es la forma en que deberíamos escribir el código, independientemente de su formato. Me refiero a aspectos que parecen a priori tan triviales como: información a incluir en los comentarios, nombres a usar como variables, estructura de directorios del proyecto, … En este sentido, creo que se comprende mucho mejor mostrando contraejemplos, o dicho de otro modo, enseñando cómo no se deben hacer las cosas. Próximamente iré publicando algunos artículos en esta línea.