Se aconseja formalmente atenerse a estas reglas. Esta cuestión no está sujeta o no a tus gustos personales: permite al proyecto conservar su coherencia y su unidad, y mantenerlo tan legible como estaba antes. No olvides que otras personas distintas a ti están obligadas a leer, entender, y tal vez modificar tu código.
Por ejemplo, es evidente que las funciones de SPIP están escritas de forma mi_funcion(). En el marco de este proyecto, estaría por lo tanto completamente fuera de lugar añadir funciones escritas como MiFuncion() - aunque en absoluto esta forma no es más criticable que la otra.
Evidentemente, todo esto no impide criticar una regla y proponer otra mejor, llegado el caso. No dudes en hacerlo; pero tiene que haber buenas razones para ello.
En fin, toda regla tiene excepciones. Pero estas deben tener una verdadera justificación, no sólo la pereza del programador; deben ser lo más escasas posible. En especial, hay que tener presente que lo «provisional» tiene bastante tendencia a convertirse en definitivo cuando nadie se preocupa de corregirlo; claramente es lógico y justo que todo programador sea responsable del acabado de su propio código, pero no del de los demás.
Reglas de presentación y de escritura
Las reglas siguientes son comunes para un número más o menos grande de lenguajes de programación: al menos todos los lenguajes que tienen una sintaxis similar a PHP (es decir, además del propio PHP, C, C++, Java....).
Estas son reglas aceptadas comúnmente, de forma tan natural como las reglas de presentación y de tipografía de un texto en lenguaje natural; de hecho es frecuente que sean similares.
Presentación
- El código debe estar espaciado e indentado de manera que resalte su estructura y la separación entre los diferentes bloques lógicos (en especial las funciones). El espaciado y la indentación deben ser suficientes para hacer comprensible la estructura desde el primer vistazo; tampoco deben ser excesivos. Se le debe prestar la misma atención que a la división en párrafos de un texto en lenguaje natural.
- La indentación se hará preferentemente con el carácter de tabulación. Eso permite elegir libremente la profundidad de indentación en las opciones de tu editor de texto, sin imponer esa elección al resto de desarrolladores.
- Todo bloque contenido en el interior de un par de llaves se indentará con una sola tabulación. Lo mismo, de forma recursiva, para los sub-bloques: añadir una única tabulación suplementaria por cada salto a un nivel suplementario de profundidad. Esta regla también sirve para la declaración de funciones.
- El código que no forma parte de una función no debe estar indentado.
- El uso de las transiciones PHP-HTML (<?php y ?>) debe ser minimizado. Evitarlo cuando haya que mostrar únicamente pequeñas partes de HTML. No olvidar que un trocito de código PHP insertado en medio de un océano de HTML es invisible sin un examen muy atento.
Tipografía
- Cuando se usen paréntesis o corchetes, no hace falta dejar espacio después del paréntesis de apertura ni antes del paréntesis de cierre.
- Cuando se usen operadores binarios (+, =, *, AND, ...), hay que dejar un espacio a ambos lados del operador. La excepción manifiesta a esta regla, es cuando los operadores se mencionan y no son usados como tales.
- Los operadores unarios (!, ...) deben estar pegados al parámetro al cual se aplican.
- Por convención, después de la llamada a una función, no hay espacio antes del paréntesis de apertura: «f($x)» y no «f ($x)». Al contrario, y para distinguirlo bien, se deja un espacio antes del paréntesis cuando se trata de una estructura de control integrada en el lenguaje: «if (!$x)» y no «if(!$x)».
- La coma y el punto y coma van seguidos por un espacio; pero no precedidos por él.
Reglas de programación
Reflexionar
Antes de programar una nueva característica, reflexionar sobre...
- métodos y algoritmos usados para la implementación: ligereza, prestaciones, robustez (no dudes en hacer algún cálculo aproximado para validar tu elección);
- adecuación al proyecto: portabilidad, seguridad, flexibilidad;
- implicaciones para el resto de características: modificaciones y añadidos que hay que hacer en las características existentes;
- lugar «natural» para esta característica dentro del proyecto: en cuanto a la interfaz, a los ficheros...
No olvidar la «factorización» o puesta en común del código (para las funciones, y especialmente para los ficheros a incluir). Evitar en cambio mientras sea posible los ficheros incluidos que contengan código fuera de funciones (salvo cuando esto es «natural» y es lo que se desea).
Dar nombre
- Variables y funciones :
Sea cual sea el proyecto, el modo de dar nombres debe ser homogéneo para que el código sea fácil de leer. Así, bajo SPIP, los nombres de las variables y los de las funciones estarán en minúsculas; con los nombres compuestos, de la forma variable_compuesta.
De manera general, los nombres no serán ni muy breves, ni demasiado largos; y serán suficientemente explícitos. Esta regla es particularmente importante para las variables globales, que pueden estar compartidas por varios ficheros y numerosas funciones. Para las variables locales (i.e. en una función), la regla es más flexible. Notablemente, se pueden emplear variables de una letra, por ejemplo para obtener expresiones más compactas. Recordamos que en todos los lenguajes de programación, un cierto número de letras se asocian, por tradición, con determinados usos (ejemplos: $i, $j para los contadores de bucles, $n para una denominación, $t para un instante o una duración en segundos...). No cambiar esas convenciones permite que los lectores vayan al grano más rápidamente.
- Ficheros :
Por razones históricas, los ficheros a incluir en el espacio público se llamarán inc-fichero.php3. En el espacio privado, esto será ecrire/inc_fichero.php3 (nótese el guión bajo en lugar del guión normal). Los ficheros del espacio público llamados mediante redirección HTTP desde el espacio privado se llaman spip_fichero.php3. Todos los demás ficheros tienen un nombre que no comienza ni por "inc", ni por "spip".
Probar
Una vez aportada una modificación importante, es bueno comprobarla por si mismo, sin esperar a que alguien lo haga en nuestro lugar. En el marco de SPIP, esto quiere decir verificar que el programa funcione correctamente en un cierto número de alojamientos Web (por ejemplo: Altern, Free...) y de configuraciones (por ejemplo : diferentes versiones de PHP, de MySQL, restricción mayor o menor de los derechos de acceso a los directorios...); y también que un determinado número de las situaciones más habituales (sobre todo en el caso de una interfaz gráfica) se efectúen correctamente.
Compartir tus modificaciones
Una vez que estés satisfecho con la modificación del código, es el momento para hablar con los demás desarrolladores de SPIP, y para ver si merece ser integrado en la distribución oficial de SPIP... Unete a la lista de correo spip-dev. ¡Hasta pronto!