Saltar al contenido principal

EST-TDT-02 Estándar para Comentarios de Código XML en Formato XSD

v 1.0

Propósito​

El propósito de este documento es establecer un estándar para la documentación de código XML utilizando el formato XSD en los proyectos de desarrollo de software de Black Dot. Este estándar busca mejorar la comprensión, el mantenimiento y la trazabilidad del código a través de comentarios estructurados y consistentes en el formato XSD, que facilita aún más la colaboración y el entendimiento entre los miembros del equipo.

Descripcion Inicial​

Una documentación clara y efectiva es esencial para el desarrollo y mantenimiento eficaz del software. Los comentarios adecuados en el código XML, estructurados en el formato XSD, aseguran que todos los aspectos del código sean fácilmente comprensibles y mantenibles, y contribuyen a una mayor coherencia en la documentación.

Involucrados​

Equipo de desarrollo de software de Black Dot.

Descripción del Estándar​

1. Comentarios Generales​

  • Ubicación: Al principio de cada archivo XML.
  • Propósito: Describir el propósito general del archivo, incluyendo cualquier dependencia o requisito específico, utilizando el formato XSD para una estructura uniforme y clara.
  • Ejemplo: 
    <!-- Descripción: Este archivo define las vistas y acciones para el módulo de preguntas. Dependencias: Requiere modelos de datos 'pregunta' definidos en el sistema. -->

2. Comentarios de Sección​

  • Propósito: Dividir el archivo en secciones lógicas y explicar el propósito de cada sección utilizando el formato XSD.

  • Ejemplo:

    <!-- Sección de Configuración de Acciones -->

    <!-- Sección de Configuración de Vistas -->

3. Comentarios de Elemento​

  • Descripción: Documentar cada elemento XML significativo, especialmente aquellos que no son autoexplicativos, usando el formato XSD para mantener la consistencia.

  • Ejemplo:

    <!-- Elemento que define la acción para abrir la vista de preguntas -->

    <record id="pregunta_action" model="ir.actions.act_window">
      <field name="name">pregunta.action</field>
      <field name="res_model">pregunta</field>
      <field name="view_mode">tree,form</field>
    </record>

4. Comentarios de Atributo​

  • Explicación: Añadir comentarios para explicar el propósito de atributos específicos dentro de los elementos cuando no sean evidentes, utilizando el formato XSD para una mejor claridad.

  • Ejemplo:

    <!-- 'view_mode' define los modos de vista disponibles para esta acción (vista de árbol y formulario) -->
    <field name="view_mode">tree,form</field>

5. Directrices de Formato​

  • Consistencia: Mantener un estilo de comentario consistente en todo el código XML, utilizando el formato XSD para todos los comentarios.
  • Brevedad: Hacer los comentarios informativos pero concisos.

6. Validación de Comentarios​

  • Revisión Regular: Establecer un proceso para revisar los comentarios y asegurarse de que sigan siendo relevantes y correctos con las versiones actuales del código, evaluando especialmente la adherencia al formato XSD.

Beneficios Esperados​

  • Claridad Mejorada: Facilitar a los nuevos desarrolladores y a otros miembros del equipo la comprensión del código.
  • Mantenimiento Eficiente: Reducir el tiempo necesario para realizar cambios y actualizaciones al facilitar la comprensión rápida del código y su estructura, mejorada por el uso del formato XSD.

Control de cambios​

VersiónCambio realizadoAnálisisAutorRevisor(es)Fecha de cambio
v 1.0Creación del documentoN/AMike30/04/2024