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.