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:

/**
 * 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
 */

API

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


Revisão #3
Criado 26 June 2017 17:03:58 por JACKSON YANNO ARAUJO DE CARVALHO
Atualizado 6 September 2017 05:24:20 por JACKSON YANNO ARAUJO DE CARVALHO