Presentar/explicar el código y las decisiones de diseño a los miembros del equipo

Question

Estoy trabajando en un proyecto donde tendré que justificar y explicar regularmente mi código y decisiones de diseño a los miembros del equipo que no están directamente involucrados en la misma área del proyecto que yo a.m.

¿Cómo puedo explicar mejor mis decisiones de diseño técnico a los miembros del equipo en una ubicación diferente? ¿Los tutoriales sobre el código valen la pena para los miembros del equipo que no están directamente involucrados, o las explicaciones escritas y el código anotado serán mejores? Si decido comentar en detalle mi código para explicar las decisiones de diseño, ¿debería hacerlo en una copia por separado del código?

Answer 1

Me gustan los diagramas simples dibujados a mano para las explicaciones de diseño. Pero hay que mantenerlo realmente simple, no sobrecargarlo con diagramas de arquitectura completa y cada pequeño detalle. Hablar con sus colegas sobre el diagrama será una buena discusión y si hacen preguntas al respecto, el tiempo vale mucho más que un discurso propio.

Cuando se trata de documentar el código, soy un gran admirador de Clean Code. Si está nombrando cuidadosamente todo, solo debería dejar caer una línea de comentario si realmente hay una decisión de diseño detrás del código que le hizo elegir una forma poco común. Generalmente evito mucha documentación (como javadoc) en mi código.

Aquí es lo que hago:

• guardo métodos simples
• 1 nivel de detalle en sus métodos
• buenos nombres para las variables, métodos, clases

También trato de evitar las cosas de hackers en mi código. Si necesita explicar una sola línea en su código, porque utilizó la manera más elegante y más corta de hacer las cosas, probablemente enloquezca al desarrollador siguiente.

Y, la gran cosa: Proporcionar casos de prueba (tal vez las pruebas de unidad) para su código, por lo que otros desarrolladores puedan ejecutarlos, ver lo que sucede y, de hecho ver cómo estaba destinado su código para ser utilizado. Creo que tener casos de prueba como una forma de documentar tu código es una forma muy agradable para que otros desarrolladores se acostumbren a tu código. Las mismas reglas se aplican a los casos de prueba que a su código: Haga que esté limpio.

Answer 2

Añadir buenos comentarios al código real que incluye breves ejemplos, ver alsos y etc
asegúrese de incluir la ayuda HTML generado en el check-in resultados
(hace que la documentación más fácil para que otros puedan acceder).

También incluya proyectos/paquetes de demostración en la solución/proyecto que demuestren las ventajas de su diseño y cómo usar su código.
Asegúrese de que los ejemplos estén conectados a los temas en los que los demás están trabajando, esto les facilitará la conexión.

Answer 3

En mi humilde opinión, comentar bien tu código es probablemente la mejor manera de transmitir esta información. Los grandes manuales o incluso los documentos de diseño desaparecen rápidamente a medida que evoluciona la base de códigos. Además de eso, es menos probable que un programador se siente y hojee un manual denso que ir y hurgar en su código para descubrir qué está pasando.

Si su código está diseñado lo suficientemente bien como para que su estructura sea auto-documentada, los comentarios que agregue para explicar sus algoritmos y tal proporcionará el resto de la información que otros programadores necesitarán para darle sentido a su código.

Como se mencionó, es fácil extraer comentarios para generar documentos API en muchos idiomas. Esa es otra cosa útil que hacer.