En Silicon Valley, si usted detiene aleatoriamente a un programador en la calle y le pregunta: "Antes de comenzar un proyecto, ¿qué debería hacer?" nueve de cada diez probablemente responderán: "Escribe un documento de diseño". a es un archivo compartido entre los ingenieros que describe una característica a implementar antes de que se escriba cualquier código, como en Los documentos de diseño a menudo consisten en varias secciones: design document (design doc) this example Este ejemplo Resumen: Algunas frases simples que describen la característica a implementar. Motivación: ¿Por qué estamos implementando esta característica? Preview: ¿Cómo será la característica después de implementarla? Opciones técnicas: ¿Qué opciones técnicas tenemos para implementar esta característica? ¿Cuáles son los pros y los contras de cada una? ¿Cuáles elegimos y por qué? Detalles de implementación necesarios: listar plantillas de código, cómo probar, cómo escribir registros, etc. Es importante notar que un documento de diseño debe permanecer de alto nivel; la implementación específica es el trabajo del código. Un autor principal elabora el documento de diseño, y sus colegas se comunican con el autor comentando el documento. Este proceso de comunicación a menudo dura varios días o incluso semanas. Una vez que el autor y sus colegas acuerden el contenido del documento, se puede fusionar en la base de código. Esto también marca el inicio del proyecto descrito en el documento de diseño. Este proceso de incorporar documentos de diseño en proyectos ofrece numerosos beneficios. Si puede articular sus ideas en un lenguaje conciso y lógicamente claro, esto indica una profunda comprensión de la implementación de la característica. Por el contrario, si no puede incluso expresar lo que tiene la intención de escribir, entonces la implementación de la característica será aún más difícil. Sus colegas, al comentar su documento de diseño, también le ayudarán a revisar sus ideas, descubrir problemas de antemano, señalar fallos lógicos e incluso sugerir mejores métodos de implementación (He encontrado repetidamente que los colegas alrededor de mí vienen consistentemente con mejores soluciones e identifican lagunas lógicas en mi pensamiento). First, design documents help you clarify your thoughts. Hacen transparente el pensamiento técnico de todos, y la base de código se vuelve más mantenible.Si un documento de diseño es aprobado por todos, entonces todos tendrán más propiedad de todo el proyecto y estarán más dispuestos a ayudar a mejorar la calidad del código, lo que conduce a una alta calidad general de ingeniería para el proyecto. Second, design documents help the entire team reach a consensus. Los nuevos miembros del equipo y colegas de otros equipos pueden obtener fácilmente una comprensión de alto nivel de toda la base de código a través de los documentos de diseño.Cuando alguien quiere comprender el estado del proyecto, no hay nada más satisfactorio que simplemente enviarles un enlace. Third, design documents are an excellent supplement to code. En comparación con las reuniones largas, los documentos de diseño permiten a los colegas (en diferentes zonas horarias) reflexionar tranquilamente de forma independiente en su propio momento apropiado, refinar sus pensamientos y proporcionar feedback al autor. Las discusiones de pre-desarrollo entre los colegas pueden revisar de manera efectiva todo el enfoque de diseño, reduciendo significativamente el riesgo de diseños defectuosos (creedme, he sido más de una vez perezoso y escribió directamente el código, solo para encontrar días de mi desarrollo que resultaron inútiles). Durante el desarrollo, ya que los colegas ya entienden el concepto de diseño, las revisiones de código se vuelven más sencillas. Si surgen problemas durante el pre-desarrollo, los desarrolladores también pueden obtener más fácilmente ayuda de los colegas. Después del desarrollo, los documentos de diseño Fourth, design documents help teams save time. Los colegas que participan en las discusiones son a menudo aquellos interesados en el problema que el documento de diseño pretende resolver.A través de los documentos de diseño, pueden formar rápidamente pequeños equipos y completar tareas de manera eficiente con suficiente pasión. Fifth, design documents are excellent for organizing teams. Los documentos de diseño a menudo reflejan la alfabetización de ingeniería del autor, la claridad de pensamiento en la resolución de problemas y la capacidad de resolver problemas importantes. Sixth, design documents are excellent material for promotion. Dado que escribir documentos de diseño trae tantos beneficios a un equipo, ¿por qué no todos siguen esta práctica? "Escribir documentos de diseño es demasiado problema, tal vez sólo empiece a codificar primero?"Si encuentra que los documentos de diseño son difíciles de escribir, indica que el autor no entiende el problema lo suficientemente a fondo, y su método de implementación elegido es probablemente incorrecto.Escribir documentos de diseño ciertamente requiere mucho esfuerzo al principio, pero como se mencionó anteriormente, estas inversiones son valiosas a largo plazo. "Si salto de escribir el documento, ya habría terminado el código." Todo en moderación. Si se necesita un documento de diseño depende de la calidad y mantenimiento a largo plazo del código del proyecto. Si una característica es fácil de implementar y su lógica es sencilla, tal vez simplemente crear un problema para describir la característica sería suficiente, y el mantenimiento del código y el alineamiento del equipo se pueden lograr a través de revisiones de código. Sin embargo, para las características complejas, todavía se recomienda escribir un documento de diseño. "Soy bueno en esto, vea que lo implemento directamente e impresiono a mis colegas." Mientras que tener áreas de experiencia es un plus, la comunicación dentro del equipo es igualmente importante. Por un lado, si los colegas no entienden el enfoque del autor, es difícil para ellos realizar revisiones de código; por otro lado, el mantenedor de código y el autor a menudo no son la misma persona. Si las ideas del autor no se conservan a través de la documentación, y el código es complejo, la sostenibilidad de todo el proyecto disminuirá. Trate de cambiar estas percepciones, salga de su zona de confort, intente comenzar a escribir documentos de diseño y participe activamente en comentar los documentos de diseño de los demás. Anécdota: Una vez me quejé a un colega: "Realmente no puedo entender el código de otras personas, especialmente en idiomas como Python, que son fáciles de escribir pero difíciles de leer."El colega respondió: "No te preocupes, tampoco pueden entender el tuyo."
