# Documentação

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

##### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-documentacao#sum%C3%A1rio)Sumário

1. [Código](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/documenta%C3%A7%C3%A3o-67c#bkmrk-c%C3%B3digo)
2. [API](https://wiki.ifpe.edu.br/books/an%C3%A1lise-e-desenvolvimento-de-sistemas/page/documenta%C3%A7%C3%A3o-67c#bkmrk-api)

### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-documentacao#c%C3%B3digo)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](http://www.sphinx-doc.org/en/stable/) para Python ou o nativo [Javadoc](http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html) para Java.

Exemplos:

- Javadoc

```code
/**
 * 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
    
    ```
    <span class="s">"""
    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
    """</span>
    
    ```

### [](http://gitlab.ifpe.edu.br/filipe/guia-software-institucional/wikis/desenvolvimento-documentacao#api)API

No desenvolvimento de uma API, esta também deve possuir uma documentação *live*. Ver documentação [Swagger](http://swagger.io/).