Documentação

Sempre programe considerando que a pessoa que vai manter seu código é um psicopata violento que sabe onde você mora.

Sumário
  1. Código
  2. API

Código

Cada método deve possuir um comentário associado explicando sua finalidade, cada parâmetro e o seu retorno.

Além disso, deve ser possível acessar a documentação fora do código através de uma página passível de navegação. Para isso, podem ser usados geradores automáticos de documentação como, por exemplo, o Sphinx para Python ou o nativo Javadoc para Java.

Exemplos:

  • Javadoc
/**
 * Usado para buscar as inscrições válidas em um determinado edital.
 * Ver {@link remocao.ifpe.edu.br}. 
 * @param edital Identificador do edital
 * @return Lista de inscrições válidas.
 * @see Inscricao, Edital
 */
  • Docstring / Epydoc

    """
    Essa função é usada para gerar um número aleatório.
    
    @type  max: number
    @param max: Número máximo que o número aleatório pode atingir
    @rtype:   number
    @return:  número aleatório 0 < x < max
    """
    

API

No desenvolvimento de uma API, esta também deve possuir uma documentação live. Ver documentação Swagger.