Documento de normas

Question

Estoy escribiendo un documento de estándares de codificación para un equipo de unos 15 desarrolladores con una carga de proyectos de entre 10 y 15 proyectos al año.Entre otras secciones (que puedo publicar aquí cuando llegue a ellas), estoy escribiendo una sección sobre formato de código.Entonces, para empezar, creo que es prudente que, por cualquier motivo, establezcamos algunos estándares básicos y consistentes de formato/nombramiento de código.

He analizado aproximadamente 10 proyectos escritos durante los últimos 3 años por este equipo y, obviamente, estoy encontrando una gama bastante amplia de estilos.Los contratistas entran y salen y, en ocasiones, incluso duplican el tamaño del equipo.

Estoy buscando algunas sugerencias para el formato de código y los estándares de nomenclatura que realmente hayan valido la pena...pero eso también puede estar realmente justificado.Creo que la coherencia y los patrones compartidos contribuyen en gran medida a que el código sea más fácil de mantener...pero, ¿hay otras cosas que debo considerar al definir dichos estándares?

• ¿Cómo se alinean los paréntesis?¿Sigue las mismas pautas de paréntesis cuando trata con clases, métodos, bloques try catch, declaraciones de cambio, bloques if else, etc.?

• ¿Alinea campos en una columna?¿Anota o antepone variables privadas con un guión bajo?¿Sigue alguna convención de nomenclatura para que sea más fácil encontrar detalles en un archivo?¿Cómo ordenas a los miembros de tu clase?

¿Qué pasa con las sugerencias para espacios de nombres, empaquetado o estándares de organización/carpetas de código fuente?Tiendo a empezar con algo como:

<com|org|...>.<company>.<app>.<layer>.<function>.ClassName

Tengo curiosidad por ver si existen otras prácticas más aceptadas de las que estoy acostumbrado, antes de aventurarme a dictar estos estándares.Los enlaces a estándares ya publicados en línea también serían geniales, aunque ya he hecho un poco de eso.

Answer 1

Primero busque un formateador de código automatizado que funcione con su idioma.Razón:Independientemente de lo que diga el documento, la gente inevitablemente romperá las reglas.Es mucho más fácil ejecutar código a través de un formateador que ser quisquilloso en una revisión de código.

Si está utilizando un idioma con un estándar existente (p. ej.Java, C#), es más fácil usarlo, o al menos comenzar con él como primer borrador.Sun pensó mucho en sus reglas de formato;también podrías aprovecharlo.

En cualquier caso, recuerde que muchas investigaciones han demostrado que variar cosas como la posición de las llaves y el uso de espacios en blanco no tiene un efecto mensurable en la productividad, la comprensibilidad o la prevalencia de errores.solo tener cualquier El estándar es la clave.

Answer 2

Procedentes de la industria automotriz, he aquí algunos estándares de estilo utilizados por razones concretas:

Utilice siempre tirantes en las estructuras de control y colóquelos en líneas separadas.Esto elimina los problemas con las personas que agregan código y lo incluyen o no por error dentro de una estructura de control.

if(...)
{

}

Todos los interruptores/selecciones tienen un caso predeterminado.El caso predeterminado registra un error si no es una ruta válida.

Por el mismo motivo que el anterior, any if...elseif...las estructuras de control DEBEN terminar con un else predeterminado que también registra un error si no es una ruta válida.Una sola declaración if no requiere esto.

En el caso ocasional en el que un bucle o estructura de control esté intencionalmente vacío, siempre se coloca un punto y coma dentro para indicar que esto es intencional.

while(stillwaiting())
{
   ;
}

Los estándares de nombres tienen estilos muy diferentes para typedefs, constantes definidas, variables globales de módulos, etc.Los nombres de las variables incluyen el tipo.Puede mirar el nombre y tener una buena idea de a qué módulo pertenece, su alcance y tipo.Esto facilita la detección de errores relacionados con tipos, etc.

Hay otros, pero estos son los mejores.

-Adán

Answer 3

Voy a apoyar la sugerencia de Jason.

Acabo de completar un documento de estándares para un equipo de 10 a 12 personas que trabajan principalmente en Perl.El documento dice que utiliza la "sangría similar a la perltidia para estructuras de datos complejas". También proporcionamos a todas las configuraciones de perltidy de ejemplo que limpiarían su código para cumplir con este estándar.Era muy claro y en gran medida estándar de la industria para el lenguaje, por lo que el equipo lo aceptó muy bien.

Cuando me dispuse a escribir este documento, pregunté por algunos ejemplos de código excelente en nuestro repositorio y busqué en Google un poco para encontrar otros documentos estándar que permitieran a los arquitectos ser más inteligentes que yo a construir una plantilla.Fue difícil ser conciso y pragmático sin entrar en territorio de microgerencia, pero valió la pena;teniendo cualquier El estándar es realmente clave.

¡Espero que funcione!

Answer 4

Evidentemente varía según los idiomas y las tecnologías.Por el aspecto de su espacio de nombres de ejemplo, voy a adivinar java, en cuyo caso http://java.sun.com/docs/codeconv/ es un muy buen lugar para empezar.También es posible que desees ver algo como la estructura de directorios estándar de Maven que hará que todos tus proyectos se vean similares.