Estamos convencidos de que a documentação é muito importante para ser abandonada. Se feita corretamente, ela será uma adição valiosa e um bloco de construção importante para escrever código limpo, especialmente ao trabalhar em equipe.
Vamos abordar os seguintes tópicos principais neste capítulo:
Criamos documentação porque podemos facilitar o trabalho de outras pessoas com nosso software. Trata-se de contexto, que não pode ser facilmente extraído ao ler o código de algumas classes.
A documentação muitas vezes não se trata apenas do que ou como, mas também do porquê.
Vamos focar na documentação que o auxilia no processo de desenvolvimento e permite que você escreva um código limpo, conforme descrito na seguinte lista não exaustiva:
O que devemos documentar
Documentação da arquitetura do sistema: Assim que seu projeto se tornar grande o suficiente para que a configuração básica do servidor (geralmente um servidor web e um banco de dados em uma única máquina física) se torne um gargalo, e você começar a dimensioná-lo, deve pensar em documentar também sua infraestrutura. Eventualmente, isso economizará muito tempo para você e para os outros ao procurar os URLs corretos ou acessos ao servidor, especialmente em situações críticas. Pode ser um bom lugar para adicionar informações sobre o pipeline de integração contínua (CI) também.
Documentação da arquitetura do software: Como seu software é construído internamente? Ele usa eventos para se comunicar entre os módulos? Existem filas que devem ser usadas? Perguntas como essas devem ser respondidas na documentação da arquitetura do software. Isso facilita para outros desenvolvedores seguir os princípios.
Diretrizes de codificação: Além da documentação da arquitetura do software, as diretrizes de codificação oferecem conselhos sobre como escrever o código. Discutimos esse tópico em profundidade no Capítulo 12, Trabalhando em Equipe.
Textos
Para projetos pequenos, É recomendável fazer a documentação como uma subpasta do projeto, colocando a documentação num formato fácil de ser lido, como o Markdown.
Diagramas
Documentando API
Um formato muito popular é o de OpenAPi pela ferramenta Swagger que descreve os aspectos das API, seus end-points usando arquivo YAML (Ain’t Markup Language) como trecho a seguir
openapi: 3.0.0
info:
title: 'Product API'
version: '0.1'
paths:
/product:
get:
operationId: getProductsUsingAnnotations
parameters:
-
name: limit
in: query
description: 'How many products to return'
required: false
schema:
type: integer
responses:
'200':
description: 'Returns the product data'
A partir desse pequeno trecho o swagger consegue gerar ruma página que descreve o endpoint e a mesmo pode consumi-lo.
Ao invés de escrever todo o arquivo, você pode usar ferramentas que gerar o swagger, em https://github.com/zircote/swagger-php
Ele vai gerar a documentação de acordo com as Annotation e comentários no método. Infelizmente é necessário criar um comentário muito grande.
Swagger UI: Swagger UI
(https://github.com/swagger-api/swagger-ui), que é uma documentação visual e interativa da sua API.
Alternativas OpenAPI - RAML e API Blueprint
Existem outros formatos, como a Linguagem de Modelagem de API RESTful (RAML) (https://raml.org) ou API Blueprint (https://apiblueprint.org), que você pode usar, e não temos preferência por nenhuma solução em particular.
DockBlocks
Anotações em comentários que usam @. Tanto IDES quanto outros programa conseguem ler essa anotações e gerar documentação com informação.
Algumas ferramentas de qualidade de código usam anotações para alterar o seu comportamento.
Useless comments
Evite comentários inúteis como o a seguir:
// write the string to the log file
file_put_contents($logFileName, $someString)
Useless comments
When commenting is useful
Escrever código limpo não é apenas saber como fazê-lo por conta própria, mas também garantir que outros desenvolvedores sigam esse caminho também. Para poder fazer isso, eles precisam conhecer as regras que se aplicam ao projeto.
Neste capítulo, discutimos como criar documentação que possa ajudá-lo a alcançar esse objetivo. Discutimos as melhores práticas para escrever documentação manualmente, bem como a criação de diagramas informativos e ao mesmo tempo mantíveis. Por fim, apresentamos maneiras de gerar documentação a partir do código e elaboramos sobre os prós e contras da documentação embutida.
Documentar:
Formas de documentar:
Quando comentários no código são bons:
Documentar API: Através do Swagger
Se você deseja aprender mais sobre o Mermaid.js, recomendamos o livro “The Official Guide to Mermaid.js” de Knut Sveidqvist e Ashish Jain, publicado pela Packt em 2021.