coding-style - normas - estandares de codificacion y documentacion java

¿Cómo documenta sus estándares de codificación? (20)

Usamos lo siguiente:

Herramientas / complementos en el editor (checkstyle, pmd, herramientas internas)
Las comprobaciones de tiempo de compilación producen un informe.
La wiki se usa para documentar comentarios de revisión de código
A partir del 3, luego refactorizamos los ''aplicables'' en la herramienta interna.

¿Cuál crees que es la mejor manera de publicar tus estándares de codificación y por qué?

Nos movimos de documentos de Word que resultaron ser engorrosos y propensos a quedar obsoletos.

Páginas Wiki con los estándares y ejemplos
Herramientas de validación estándar de codificación automática que se ejecutan durante el proceso de CI

NB También tenemos un cliente que no usa ejecutar nada aparte de la construcción en sí en el ciclo de CI. Mantienen sus reglas en ReSharper y están bastante satisfechos con los resultados

Si está desarrollando en .NET. Recomendaría usar StyleCop para verificar tus compilaciones. También recomendaría usar ReSharper y el plugin StyleCop.

Con ReSharper y el plugin StyleCop, obtienes líneas rojas "onduladas" en código que está en contra del estándar y un simple sobrevolver explicará por qué. Sin revisiones de código, no hay documentos para maintian.

Usar StyleCop en su proceso de compilación asegurará que todo el código registrado se ajuste a los estándares.

Actualmente tenemos el estándar de codificación en una Wiki que solo los desarrolladores sénior tienen derecho a editar. Sin embargo, como muchas personas ya han indicado, nadie lo lee después de sus primeros días. Actualmente estamos en el proceso de tratar de obtener nuestro estándar de codificación en StyleCop en el lado .NET. Las cosas de Delphi son un poco más difíciles ya que no tenemos un marco Delphi como StyleCop para usar.

Creo que la mejor manera es utilizar Checkstyle para hacer cumplir su estándar de codificación y asegurar que la compilación falle si algunos códigos algo en contra de las reglas de estilo de control.

Luego use la revisión de código y la programación de pares para que los juniors puedan aprender de los seniors

También puedes configurar una página wiki.

Cuando he sido responsable de establecer un estándar de codificación, intento encontrar uno bueno en Internet que se adapte a nuestras necesidades y lo use. Tomaré cualquier formato que aparezca, generalmente PDF o Word.

No tiene sentido reinventar la rueda. También puedo aprovechar el arduo trabajo que alguien más ha hecho.

Cuando manejaba un equipo pequeño, nuestros "estándares de codificación" eran un script contenedor en CVS que ejecutaba sangría (con un archivo rc para todo el equipo) en su código cuando lo registraba.

Depende de las circunstancias:

Trabajé en una pequeña empresa con solo tres desarrolladores. Allí, simplemente lo discutimos . Esto significa nada más que preguntarle a sus codesarrolladores si tiene dudas sobre el estilo de codificación. Después de un tiempo, alguien se dio cuenta de que las mismas preguntas se le hicieron varias veces y abrió una página estándar de codificación en nuestro wiki.

Hoy trabajo en un pequeño laboratorio de investigación. En este campo particular, no tenemos estándares formales de codificación. Sin embargo, como trabajamos en equipos y realizamos sesiones de pareja regularmente, parece que de la nada aparece un estándar de codificación implícito.

De algunos amigos, que desarrollan sistemas para la orientación de aeronaves, sé que acuerdan estándares de codificación basados en

seguridad y restricciones gubernamentales
necesidades e insumos del departamento de control de calidad
si todavía hay libertad de elección: aporte de los desarrolladores

Este estándar de codificación está anotado y se aplica por QA.

Documentaré el código estándar por:

estructura del estilo general más importante (como indentación, ajuste de línea, llaves, ...)
a los detalles menos visibles (espacio antes / después ( o ) )
ejemplos de código
configuración de configuraciones para configurar el formateador de código de eclipse
prosa

La única forma efectiva de publicar un estándar de codificación en mi opinión es integrarlo en el ide utilizado por los desarrolladores (eclipse o idea, por ejemplo). Por lo tanto, el nuevo código seguirá los estándares de manera predeterminada y el código antiguo se podrá reformatear utilizando ide.

Solo pocos desarrolladores leerán los estándares de codificación, y pocos los usarán después ...

Las pautas del código son un documento de toda la empresa que describe las prácticas. Y está disponible y debe ser seguido estrictamente.

El formato de código estándar está sujeto a la decisión entre los miembros de un equipo (o proyecto). Para nuestro proyecto, se mantiene en SVN como un conjunto de configuraciones para el complemento Resharper .

Lo colocamos en la wiki, con enlaces a fragmentos de código donde esto es útil.

Luego configuramos un formateador de código en Eclipse para que coincida lo más posible con este estándar de codificación, aunque eso no puede ayudar con las mejores metodologías de codificación.

Nuestro proyecto se basa principalmente en Python, así que básicamente tomamos las Pautas de codificación de Python , cambiamos algo aquí y allá que no nos gustó, y las incluimos en nuestra wiki de Trac . Está vinculado directamente en la página principal para que los desarrolladores sepan dónde encontrarlo. ¡Hasta ahora, realmente ha hecho un trabajo bastante decente de seguimiento!

Si está utilizando Eclipse, puede usar formateadores (Preferencias-> Java-> Estilo de código-> Formateadores) para formatear automáticamente el código cuando se guarda el archivo fuente. Simplemente tenemos el formateador de nuestra compañía disponible en nuestra wiki y todo el mundo lo importa en Eclipse.

Lo bueno de los formateadores es que puedes decidir cuál quieres usar para que puedas tener diferentes proyectos con diferentes formatos. Sin embargo, normalmente solo usamos un formato, por lo que nuestro código es uniforme en todos los proyectos.

Si se refiere a las pautas de estilo, un documento de Word o PDF. IMO, esto es algo "inamovible", pero por proyecto (si ve algo que no funciona, corríjalo para el próximo proyecto, especialmente si es tarde en el proyecto y tiene una tonelada de código que sigue el estilo existente).

Un sitio web interno con SVN utilizado para gestionar los cambios funciona. El ''último'' está siempre disponible para el equipo en línea.

Usamos nuestro código para documentar el estándar . Esto, junto con la aplicación de los ingenieros principales / líderes, ha funcionado de maravilla para nosotros. La razón por la que no mantenemos un documento real es porque descubrimos que nadie lo lee y se vuelve obsoleto bastante rápido.

En mi humilde opinión, todo lo que se necesita para demostrar el punto es el código existente que muestra el estilo / estándar.

¡Luz de viaje!

Hemos hecho lo siguiente para documentar nuestros estándares de codificación:

Los escribió en un archivo de palabras simples. La base para esta guía de estilo fueron las Convenciones de Codificación del Sol.
Configured Checkstyle y PMD para seguir estas convenciones de codificación, además proporcionaron un espacio de trabajo predeterminado para Eclipse que tenía la configuración correcta que se ajusta a las configuraciones definidas de Checkstyle y PMD.
Se agregaron tres capítulos a nuestras convenciones de codificación que explicaban qué configuración de Checkstyle, PMD y Eclipse cumplía con qué parte de la guía de estilo, para que cada arquitecto pudiera modificar la guía de estilo y las configuraciones de Checkstyle, PMD y Eclipse.
Desarrollé pequeños complementos para que al instalar Checkstyle y PMD junto con nuestros complementos, nuestra convención de codificación definida por Checkstyle y PMD fuera la predeterminada y fácil de seleccionar.

Creemos que ayuda mucho no solo escribirlo, sino integrarlo en el entorno de desarrollo. Por otro lado, hacemos eso solo para Eclpise, porque es demasiado para hacer si quieres eso para cada IDE en la tierra.

Hago todo lo posible para que sea fácil solicitar a todos:

en primer lugar, todos en el equipo deberían aceptar aplicarlos
Comparto la configuración para editores usados (gvim, emacs ...)
Proporciono el archivo fuente vacío con el encabezado repetitivo
Resumo el estándar en una hoja de referencia única, que no muestra las reglas, sino una pieza de código debidamente formateada como estandarizada

Para el proceso inicial, una wiki preparada con subtítulos es útil para recopilar opiniones de varios desarrolladores. Una vez que se ha recopilado la retroalimentación, se puede ordenar y "publicar".

ACTUALIZAR:

Unos años más tarde, Google Docs ahora funciona como una especie de wiki.