Este documento ha sido adaptado de Sobre Jack Bradshaw . Directivas de estilo Monoplaza La documentación efectiva es la piedra angular del desarrollo sostenible; sin embargo, la inevitabilidad del crecimiento del equipo hace que sea difícil escribir documentación como equipo que no sea fragmentado e inconsistente; por lo tanto, es necesario un cierto grado de coordinación entre los contribuyentes. Incluso los ingenieros solistas, que una vez tuvieron un pase libre, ahora deben luchar con la inconsistencia de la documentación generada por la IA. Yo mismo uso la IA para generar parte de la documentación en mi repositorio, pero con el tiempo se han vuelto insatisfechos con los resultados; específicamente, la falta de coherencia y coherencia en toda la base de código. Mi primer intento de resolver este problema culminó en la creación de un Documento Estándar de Documentación General que contenía 13 reglas prescriptivas; específicamente: la documentación debe ser impersonal, objetiva, precisa, formal, literal, actual, contractual, terciaria, descriptiva, definitiva y declarativa. Era una obra de arte, impecable, sublime, un triunfo rivalizado sólo por su fracaso monumental. Mi intención era establecer estándares inequívocos que podían ser verificados y ejecutados objetivamente por la IA; sin embargo, un problema se hizo evidente con el tiempo; específicamente, mientras que algunos requisitos podían ser verificados objetivamente (como la formatación de listas), otros eran intrínsecamente subjetivos (interés, definitividad, etc.) y resultaron difíciles de evaluar; En lugar de repetir los estándares rotos, se requirió un cambio fundamental en el enfoque. Reescrito completamente el documento y divido el contenido en tres tipos: estándares (absoluto y objetivo), prácticas (subjetivo pero inequívoco) y directrices (altamente subjetivo y ambiguo), con un fuerte desvío hacia las directrices. Al centrarse en la orientación de alto nivel en lugar de las reglas rígidas, y alentar un terreno intermedio entre extremos opuestos, las nuevas directrices proporcionan un amplio espacio para la expresión individual al tiempo que desalentan los modos conocidos de anti-patrón y fracaso. Esto crea un espacio inclusivo donde los contribuyentes pueden hablar en su voz natural, sin desarmonía excesiva en el resultado, creando así una experiencia de Título: Sabiduría razonada La documentación del repositorio debe ser objetiva y basada en hechos, con referencias a la base de código y fuentes externas cuando proceda; sin embargo, la subjetividad en forma de experiencia ganada con esfuerzo es inestimable, ya que los hechos por sí solos carecen del contexto para ser útiles, y eludir las experiencias / perspectivas únicas de los contribuyentes no crea un entorno de apoyo; por lo tanto, la documentación debe contener un equilibrio de objetividad con subjetividad. Too Academic: "FooSort exhibe la complejidad computacional promedio de O(N log N) caso, como formalmente demostrado por Henderson (1984) a través de análisis amortizado utilizando funciones potenciales y métodos agregados. la validación empírica se llevó a cabo a través de la simulación de Monte Carlo a través de 10.000 conjuntos de datos uniformemente distribuidos, dando un intervalo de confianza del 95% de [0.98N log N, 1.02N log N]. La solidez algorítmica ha sido revisado por pares y publicado en ACM Transactions (DOI:10.1145/12345)." Too Poetic: "FooSort baila a través de los datos como un ballet gracioso, teciendo elegantemente elementos en sus lugares legítimos. Suena eficiencia en cada turno, una sinfonía de comparaciones orquestando el orden del caos. Rápido como relámpago, hermoso como el atardecer, transforma sus listas desordenadas en arreglos primitivos de armonía pura." (Flowery metáforas obscure significado técnico) Just Right: "FooSort clasifica N artículos en O(N log N) tiempo promedio, lo que lo convierte en adecuado para la mayoría de los casos de uso. Sin embargo, se degrada a O(N2) en datos reportados, lo que causó problemas de producción en Company X cuando las cargas de los clientes eran típicamente pre-sortadas. Por esa razón, MergeSort es preferido para cargas de trabajo de producción a pesar de factores constantes ligeramente peores." (Combina hechos objetivos con experiencia subjetiva y conclusión razonada). El equilibrio entre objetividad y subjetividad garantiza que la documentación permanezca precisa y accesible, al tiempo que crea un espacio inclusivo y de apoyo para los contribuyentes. Guía: equilibrar el minimalismo con la suficiencia Los contribuyentes deben incluir suficiente información para evitar los costes ocultos de la documentación que falta, ya que el coste de almacenar unos pocos párrafos adicionales (kilobytes) es mucho menor que el coste de la falta de contexto (por ejemplo, horas de debugging, fallas de producción, reinvención de la rueda); sin embargo, los detalles innecesarios vencen el propósito ocultando la verdad bajo detalles innecesarios; por lo tanto, la documentación debe omitir la información innecesaria. Too Minimal: "FooProvider cache valores." (Contexto insuficiente sobre el comportamiento, la expiración o los problemas conocidos) Too Verbose: "FooProvider utiliza internamente un ConcurrentHashMap instantiado con una capacidad inicial de 16 y un factor de carga de 0,75 para almacenar los valores en caché, que son ellos mismos envueltos en un objeto CacheEntry personalizado que contiene un timestamp de 64 bits derivado de System.nanoTime() para cálculos de expiración de alta precisión, y son evictibles usando una política menos recientemente utilizada implementada a través de una lista sincronizada doblemente vinculada que es atravesada en orden inverso durante los ciclos de limpieza desencadenados por un servicio ScheduledExecutorService que se ejecuta en un hilo de daemon separado. Just Right: "FooProvider cache valores con un TTL de 60 segundos usando una política de expulsión de LRU. El cache se ejecuta en un hilo de fondo y puede causar errores OOM en dispositivos Android con restricción de memoria." (contexto suficiente sobre el comportamiento y los problemas conocidos sin detalles innecesarios de implementación). El equilibrio entre el minimalismo (evitar los detalles innecesarios) y la suficiencia (proporcionar un contexto adecuado) garantiza que la documentación permanezca útil y accesible sin ocultar la información crítica bajo los detalles excesivos de la implementación. Guía: Equilibrio pasado, presente y futuro La documentación debe relacionarse con el estado actual del repositorio, ya que documentar el futuro corre el riesgo de inexactitud a medida que cambian los planes, y documentar el pasado puede confundir el repositorio con información obsoleta; sin embargo, el contexto histórico a menudo justifica el presente mientras se protege contra la repetición de la historia, y reconocer oportunidades para obras futuras destaca deficiencias conocidas; por lo tanto, el pasado y el futuro deben referirse cuando es útil. Too Past-Focused: "Implementaciones pasadas de este método usaron la biblioteca matemática estándar.Había problemas con el parser pero fueron corregidos." (Detalles irrelevantes sin contexto actuable) Too Future-Focused: "En Q4 planeamos reescribir el parser. Vamos a hacer este método asincrónico en v2.0." (Promesas sin contexto sobre el estado actual) Just Right: "Se utiliza un analizador personalizado porque el analizador de biblioteca estándar causó regresiones de rendimiento en v1.2. Este método es sincronizado, pero se puede añadir soporte asíncrono en una versión futura (tracked by issue #123)." (Estado presente justificado por el contexto histórico y limitaciones conocidas reconocidas con la referencia de seguimiento). El equilibrio entre la estabilidad (documentar lo que existe) y el contexto (proporcionar los antecedentes necesarios) garantiza que la documentación permanezca precisa y útil, preservando al mismo tiempo el historial útil y reconociendo las restricciones conocidas. Nota: Vincular planes futuros a referencias de seguimiento externas ofrece a los lectores una manera de seguir y obtener actualizaciones. Guía: Equilibrar la precisión con la simplicidad La documentación debe ser técnicamente exacta y precisa, ya que las descripciones vagas conducen a malentendidos y a un uso incorrecto; sin embargo, los detalles técnicos excesivos pueden obscurecer el concepto central y abrumar a los lectores; por lo tanto, los contribuyentes deben proporcionar explicaciones precisas sin una complejidad innecesaria. Too Vague: "FooProvider hace objetos cuando los necesitas." (Falta precisión técnica sobre el comportamiento) También Detallado: "El FooProvider utiliza un mecanismo de instantiación de patrón de fábrica en el que cada invocación del método de accesorio desencadena la asignación de la memoria heap a través del nuevo operador, lo que resulta en la construcción de una instancia Foo distinta con su propia dirección de memoria." Just Right: "El FooProvider crea una nueva instancia de Foo en cada llamada." (descripción técnica precisa sin complejidad innecesaria). Atraer un equilibrio entre la precisión (ser técnicamente correcto) y la simplicidad (ser comprensible) asegura que la documentación transmite información precisa sin abrumar a los lectores con minuciosas implementaciones. Equilibrio entre formalidad e informalidad La documentación debe utilizar un lenguaje profesional que mantenga la credibilidad y la claridad, ya que el slang informal puede alienar a los lectores y reducir la autoridad percibida; sin embargo, la expresión académica o formal crea barreras cognitivas y distancia a los lectores; por lo tanto, los contribuyentes deben usar inglés técnico claro y estándar. Too Informal: "El compilador de Kotlin es bastante cool y simplemente convierte tu código en bytecode o cualquier cosa para diferentes plataformas como JVM y cosas." (slang casual socava la credibilidad) Too Formal: "El proceso de compilación de Kotlin culmina en la generación de bytecode para la máquina virtual de Java y artefactos análogos para sustratos de ejecución alternativos." Just Right: "Kotlin compila para la JVM y otras plataformas (por ejemplo, JS, nativo)." (Tono profesional con terminología clara y estándar). El equilibrio entre la formalidad (mantenimiento de la profesionalidad) y la informalidad (estar accesible) asegura que la documentación permanezca creíble y autoritaria, al tiempo que es accesible a los ingenieros generales. Guía: Referencias específicas de grupos La documentación a menudo requiere referenciar a las personas o equipos detrás de las decisiones y acciones, ya que la atribución proporciona responsabilidad y contexto; sin embargo, los pronomes personales ("nosotros", "yo", "nosotros", etc.) son ambiguos; por lo tanto, los contribuyentes deben usar nombres específicos de individuos o grupos donde sea posible. Too Vague: "El FooProvider es recomendado." (Recomendado por quién?) Too Vague: "Decidimos eliminar a los conductores" (No está claro a quién se refiere el "nosotros") Just Right: "El equipo del núcleo decidió eliminar los controladores para el rendimiento en tiempo de ejecución." (atribución específica con razonamiento claro). El equilibrio entre atribución (proporcionando responsabilidad y contexto) y claridad (evitando pronombres ambiguos) asegura una comunicación clara utilizando referencias de grupo específicas (por ejemplo, "The Maintainers", "The Compiler Team", "The Security Workgroup") en lugar de pronombres vagos. Excepción: los pronombres que se refieren al usuario (por ejemplo, "tu") son aceptables (relacionados con Balance Declarative y Imperative Tone). Tono declarativo e imperativo de equilibrio La documentación debe describir el contenido del repositorio declarando sus comportamientos y propiedades, ya que esto mantiene el foco en los artefactos que contiene; sin embargo, los procedimientos, tutoriales y guías pueden ser más claros cuando se escriben directamente al lector con instrucciones imperativas; por lo tanto, los contribuyentes deben ajustar el tono al contexto. Too Imperative: "Tienes que configurar el FooProvider antes de usarlo.Tienes que llamar el método init() primero." (Commandos en la documentación de referencia) Too Declarative: "La meta //foo:bar genera artefactos cuando se ejecuta." (descripción pasiva en un tutorial donde se necesita orientación paso a paso) Just Right: "Documentación de referencia: FooProvider debe ser configurado antes de usar llamando init(). Tutorial: Generar los artefactos mediante la ejecución de bazel run //foo:bar." (tono declarativo para las descripciones del sistema, tono imperativo para la orientación procedimental). El equilibrio entre el declarativo (definir el sistema) y el imperativo (dirigir al lector) asegura que la documentación proporcione información adecuada para su contexto, con la documentación de referencia centrada en artefactos y tutoriales que proporcionen pasos accionables claros. Guía: Equilibrio entre confianza y humildad La documentación debe ser escrita con confianza cuando el contenido es bien comprendido, ya que la cobertura innecesaria socava la autoridad y crea duda cuando no debería existir; sin embargo, hablar con una convicción excesiva cuando la verdad es incerta puede disuadir de la credibilidad; por lo tanto, los contribuyentes deben equilibrar la confianza con la humildad al reconocer las limitaciones del conocimiento y ser transparentes acerca de su incertidumbre. Too Hesitante: "FooProvider probablemente no es seguro y hay un pequeño riesgo de fracaso en el tiempo de ejecución." (Hedging innecesario sobre el comportamiento conocido) Too Confident: "FooProvider definitivamente trabajará bajo alta presión de memoria." (confianza falsa sobre el comportamiento no probado) Just Right: "FooProvider no es seguro.El comportamiento bajo alta presión de memoria es indefinido y no ha sido probado." (Confía sobre hechos conocidos, honesto sobre desconocidos). El equilibrio entre la confianza (establecer autoridad) y la humildad (reconocer límites) garantiza que la documentación mantenga la credibilidad sin generar dudas innecesarias. Guía: Juicio de equilibrio con neutralidad Los contribuyentes deben ejercer el juicio para identificar problemas reales, limitaciones y restricciones; sin embargo, el lenguaje de juicio que ataca sistemas, plataformas o contribuyentes es inútil; por lo tanto, los contribuyentes deben centrarse en descripciones factuales sin atribuir la culpa o hacer caracterizaciones negativas generalizadas. Too Neutral: "Esta implementación funciona en todas partes." (falta de juicio, ignora las restricciones reales) Too Judgmental: "Android es un sistema operativo tan tonto que ni siquiera puede ejecutar esto, también ¿quién escribió esta mierda?" (ataque personal a la plataforma y a las personas) Just Right: "Los dispositivos Android alrededor de 2012 tienen limitaciones de memoria que impiden que esta implementación funcione como se pretendía.La implementación Foo no funciona en Android." (Juicio de sonido con descripciones específicas, informativas y factuales). El equilibrio entre el juicio (identificar los problemas reales y las restricciones) y la neutralidad (evitar los ataques personales y la culpa) asegura que la documentación proporcione información precisa y útil sin recurrir al juicio. Guía: Considerar el equilibrio con el respeto Los contribuyentes deben mostrar consideración para el lector al reconocer las dificultades potenciales y ofrecer orientación de apoyo, con el lenguaje suavizador utilizado apropiadamente; sin embargo, las afirmaciones y suposiciones sobre las capacidades mentales o físicas del lector pueden ser contraproducentes, ya que cruzan una frontera interpersonal crítica; por lo tanto, la documentación debe ofrecer opciones y consejos, al tiempo que da al lector el beneficio de la duda y evita evaluaciones personales. Too Dismissive: "Este comportamiento es obvio y debe ser fácil de entender." (falta de consideración para los desafíos potenciales del lector) Too Presumptuous: "Probablemente encontrará este objeto confuso, y probablemente debería leer la guía de solución de problemas cuando se encuentre atrapado." (Hace afirmaciones sobre las capacidades y la experiencia del lector) Just Right: "Este objeto no implementa completamente el contrato de interfaz, y puede arrojar errores de maneras inesperadas.Los llamados pueden querer usar Bar en lugar de un servicio listo para la producción. La documentación completa se proporciona en el README." (Reconoce las limitaciones, ofrece opciones, permanece neutral y respetuoso). El equilibrio entre la consideración (reconocer los desafíos potenciales) y el respeto (evitar las suposiciones sobre el lector) asegura que la documentación proporcione orientación de apoyo sin cruzar fronteras interpersonales o hacer suposiciones sobre capacidades. Guía: Equilibrio de la abstracción con claridad La documentación debe utilizar abstracciones apropiadas que coincidan con el diseño del sistema, ya que la abstracción oculta detalles innecesarios de implementación y ayuda a la comprensión; sin embargo, el lenguaje narrativo y colorido puede obscurecer la verdad bajo capas de indirección conceptual; por lo tanto, los contribuyentes deben centrarse en descripciones claras y directas del comportamiento del sistema. "Foo funciona como un cinturón de transporte, la primera barra en el cinturón se procesa, luego la siguiente, y así sucesivamente, hasta que el cinturón está vacío, y el operador va a almorzar cuando no hay nada que hacer." Too Imperativo: "Foo envuelve cada objeto de barra como un nodo, cada uno con un enlace al nodo siguiente/anterior, y mantiene una referencia a un nodo (nodo raíz marcado), luego sigue recursivamente los enlaces entre los nodos para procesarlos en el orden en que se añadieron. Just Right: "Foo procesa los objetos de bar usando una cola FIFO, y se desplaza mientras la cola está vacía.Foo utiliza el patrón pub-sub para procesar los objetos de bar de forma asíncrona." (Claro, descripciones directas con abstracción apropiada). El equilibrio entre la abstracción (ocultar los detalles de la implementación) y la claridad (evitar el peso narrativo) asegura que la documentación explique claramente la implementación sin indirecciones conceptuales innecesarias. Guía: Documentación de equilibrio de proximidad con el tamaño La documentación debe distribuirse cerca de los artefactos a los que se refiere, ya que esto evita que los lectores se vean abrumados por documentos monolíticos y les ayuda a encontrar información fácilmente; sin embargo, la difusión de información en demasiados documentos obscurece el significado y deja a los lectores sin una imagen coherente; por lo tanto, los contribuyentes deben equilibrar la colocación con la cohesión. Too Centralized: El repositorio raíz README que contiene documentación para todo el repo. (Overwhelming, difícil de navegar) Too Fragmented: Una lectura en cada paquete con detalles de ese paquete solo, sin una visión general o contexto sobre cómo se relacionan los paquetes. (falta de cohesión) Just Right: Una README raíz que introduce la estructura y la filosofía del repositorio, con READMEs granulares más pequeños para paquetes grandes. (distribución equilibrada con visión general y detalle). El equilibrio entre la colocación (mantener la información cerca de donde importa) y la cohesión (proporcionar una imagen unificada) asegura que la documentación sea accesible sin ser abrumadora o fragmentada. Nota: Dividir un documento en un directorio en varios archivos en el mismo directorio puede ayudar cuando la información está en el lugar correcto, pero el documento se está volviendo demasiado grande. Práctica: Documentación adecuada al alcance La documentación granular (por ejemplo, Javadoc, comentarios en línea) debe centrarse en el componente al que se refiere; mientras que la documentación de alto nivel (por ejemplo, READMEs, documentos de arquitectura) debe centrarse en cómo los componentes se integran y componen juntos, y cómo se encajan en el sistema más amplio. Ejemplo positivo: Javadoc explicando los parámetros de una función, el valor de retorno y los casos de borde. Ejemplo negativo: Javadoc explicando toda la arquitectura del sistema. Ejemplo positivo: README explicando cómo interactúan los paquetes y la filosofía general del diseño. Ejemplo negativo: README explicando la implementación interna de cada función. Esto asegura que los lectores puedan encontrar la información adecuada en el nivel adecuado de abstracción sin redundancia o desajuste de alcance. Estándar: inglés americano El inglés americano debe utilizarse, salvo que las convenciones de dominio dicten lo contrario (por ejemplo, referenciando un objeto Colours de un paquete de terceros). Ejemplo positivo: “Color” Ejemplo negativo: “color” Esto asegura la coherencia en toda la base de código y se alinea con las convenciones generales de ingeniería de software. Excepción: Cuando la API/sistema subyacente que se está documentando utiliza otro idioma, entonces la documentación debe coincidir. Etiquetas: ortografía correcta Toda ortografía debe ser correcta. Ejemplo positivo: “requisitos” Ejemplo negativo: “requisitos” Esto mantiene la profesionalidad y evita la mala comunicación. Estándar: No Comma después de abreviaturas Las comas deben omitirse después de las abreviaturas. Un buen ejemplo es “etc”. Ejemplo negativo: «etc. » Esto reduce la confusión visual. Estándar: No Ampersands La palabra "y" debe usarse en lugar del símbolo ampersand "&". Ejemplo positivo: "Estándares y prácticas" Ejemplo negativo: "Estándares y prácticas" Esto adhiere a las convenciones formales de escritura y mejora la accesibilidad.
