Documentação Viva - Parte 2

Autodocumentação — é a documentação em um formato adequado, normalmente etiqueta, sinais ou instruções simples incorporadas, anexadas ou próximas ao dispositivo. Isso permite que o dispositivo seja usado, operado, alterado e reparado seguindo as instruções sem ter que procurar outra forma de documentação.

Para aqueles de vocês que pensam que o DOORS é algum tipo de novo sistema operacional ou metodologia, prepare-se para se divertir. Achei que seria divertido explicar o que é autodocumentação e vários estilos através de exemplos. O dispositivo mais fácil e familiar para todos nós é uma porta. A operação padrão e o uso de uma porta são conhecidos por todos, no entanto, a autodocumentação pode ser essencial em determinadas situações. Nas imagens a seguir cada porta possui documentação explícita ou descrição implícita, que estão resumidas nos títulos. À medida que você visualiza cada um, tente contemplar qual seria o equivalente “rótulo, sinal ou documentação” no mundo do código-fonte do software.

Formas de software autodocumentado

• readme.txt — O começo humilde da documentação, um único arquivo de texto ASCII deixado em uma pasta, contendo o máximo de orientação possível para o próximo visitante. Não estruturado e com capacidade limitada para incluir diagramas ou estruturas complexas devido ao formato primitivo. No entanto, a graça salvadora é que ele resiste ao teste do tempo e pode ser acessado e visualizado sem qualquer conjunto de ferramentas de suporte complexo. Na verdade, pode incluir apenas as instruções para inicialização e download de ferramentas suficientes para visualizar o restante do projeto.
• readme.md — A próxima evolução do readme.txt usando formatação markdown que pode ser adicionada usando qualquer editor de texto. Suportando a capacidade de renderizar uma versão visualmente mais atraente do conteúdo, incluindo títulos, marcadores, formatação de código e hiperlinks.
• nomes de arquivos — têm nomes de arquivos que têm valor significativo em sua descrição. Eles descrevem o conteúdo do arquivo ou a finalidade do módulo. Ninguém gosta de um projeto com arquivos chamados mod1.c, mod2.c, mod3.c. Ter um arquivo chamado DRV-PCB123REV2.C que é um driver para uma placa de circuito embutido específica de número de peça 123 e revisão 2 é claro e fácil de encontrar, especialmente se for uma convenção de nomenclatura de arquivo.
• cabeçalhos de arquivo — comentários de formato livre na parte superior de um arquivo para explicar o contexto do arquivo em um formulário de alto nível.
• palavras- chave — podem ser usadas para identificar um local no código-fonte onde um determinado tipo de informação deve ser adicionado automaticamente, normalmente pelo sistema de gerenciamento de configuração, como subversion ou git . Essas informações podem ser um histórico básico de commits, o autor, a data de criação do arquivo ou a última edição.
• cabeçalhos de função — comentários de formato livre no início de um método ou função para explicar o propósito de alto nível do código, sua estrutura, variáveis ​​e fluxo de processamento.
• comentários de estilo javadoc — os comentários de estilo javadoc dentro de um estilo delimitado e estruturado para permitir a extração automática (e inserção) de texto.
• comentários de código — comentários sobre ou ao lado de linhas de código-fonte complexo ou ambíguo.
• convenções de nomenclatura — explicação mais longa e descritiva da variável ou função. ex . Total = Preço + Imposto ; é muito mais claro que i=j+k; Originalmente, quando o tamanho do código era limitado por sistemas de armazenamento, os programadores escreviam em um formato compacto e abreviado (para uma linguagem que suporta abreviações em grande escala, confira a linguagem MUMPS /M ). À medida que os dispositivos de armazenamento de hardware e linguagens foram desenvolvidos, nomes mais longos para variáveis ​​e funções foram suportados, mas requer disciplina para usá-los. A notação húngara é um estilo que inclui a descrição do tipo de uma variável, útil em algumas situações, mas pode complicar demais a nomenclatura e tornar a legibilidade mais difícil, por exemploiage (é para idade e tem um prefixo 'i' indicando que é um número inteiro).
• nomes não números mágicos — explique o motivo da escolha de um número, para permitir que o leitor entenda sua derivação, importância e unidades.
  por exemplo , timeout = 30
  não explica por que o valor de 30 foi escolhido, e se ocorrer em vários lugares no código também é difícil entender se os motivos são os mesmos. Enquanto
  timeout = RFC7231_REQUEST_TIMEOUT_IN_SECONDS
  transmite muito mais informações ou
  timeout = RFC7231_REQUEST_TIMEOUT_IN_SECONDS — ADJUSTMENT_FOR_DEVICE_AB123_THAT_IS_NOT_RFC_COMPLIANT
  mostra o design puro e o ajuste prático que teve que ser implementado por motivos de compatibilidade.
• espaço em branco — o uso de espaço em branco ao redor do código-fonte pode melhorar a legibilidade e também ajudar a delinear o fim de um método e o início de outro.
• tags — palavras-chave deixadas como comentários são fáceis de pesquisar e indicam um local onde é necessário mais trabalho, como TODO, FIXME .
• linguagem de programação — certas linguagens, como gherkin , usadas para BDD, permitem que o inglês natural seja usado apenas com convenções e palavras-chave mínimas para adicionar estrutura a ele.

Há muito que o autor de software pode fazer para tornar o propósito e as razões de suas decisões mais claras para a próxima pessoa a olhar e trabalhar no código. Ao prestar atenção a todos os itens acima, o software pode ser autodocumentado e ser menos dependente de outras fontes externas de informação. Isso é um benefício, pois a documentação separada pode ser difícil de encontrar, acessar e relacionar no contexto de destino.

Leitura adicional

Documentação Viva — Breve História e Evolução do Conceito