Documentação de Programas em Python

def soma(a, b):
    """Retorna a soma de a e b."""
    return a + b

def calcula(x):
    return x**2 + 1
    '''
    Calcula o quadrado de x e soma 1.
    Retorna o resultado.
    '''

Texto original

O texto original pode conter falhas de gramática ou de concordância, isso ocorre porque ele foi obtido por um processo de extração de texto automático.

Texto extraído do video Algoritmos e Programação de Computadores I - Documentação de programas

O LAPI, pessoal, bem-vindos novamente a nossa disciplina de algoritmos e programação de computadores, um para o universo.
Vamos dar continuidade ao nosso As As Aulas.
Essa é a videóloga número 14 e o assunto desta videóloga é a documentação de programas.
Por que é importante documentar os nossos programas, os nossos códigos? O que isso vai afetar o desempenho ou a legibilidade do código? Então, vamos discutir um pouquinho isso na aula de hoje.
Bom, a documentação, pessoal, é de programas, permite que os usuários entendam o que o programa faz.
Então, você tem a perspectiva de uma pessoa que vai simplesmente utilizar o teu código, o teu programa.
Então, por meio da documentação, você vai informar esse usuário como executar aquele programa ou o que ele faz, o que o programa espera o comentado, o que ele vai gerar como saída.
E também você tem a perspectiva do desenvolvedor.
Então, o desenvolvedor, por meio da documentação, permite que a documentação permite que esses desenvolvedores entendam como o programa vai funcionar de modo a favorecer depois a manutenção daquele código, ou a extensão, adicionando novas funcionalidades, resolução de bugs, etc.
Então, você tem duas perspectivas diferentes aí de documentação.
A documentação voltada para o usuário e a documentação voltada para desenvolvedores.
E é importante, a gente documentar os nossos códigos até mesmo para o autor daquele código.
Porque a medida que o programa se torna mais e mais complexo, com mais linhas, etc.
O desenvolvedor ele pode se esquecer daquele trecho que ele implementou anteriormente.
Então, normal que a implementação de um aplicativo demore algumas semanas meses e até mesmo alguns anos.
E aqueles códigos que foram implementados lá no início, o programa do ele vai não vai mais se lembrar depois de um tempo.
Então, você documentar, você deixar claro ali em termos mais legíveis, o que aquele código faz.
Isso vai facilitar até mesmo a própria vida do autor daquele programa.
Para documentar um código em Python, normalmente até em Python, como também outras linguagens, isso é feito por meio de comentários.
O que é um comentário? Um comentário, pessoal, são palavras, são frases que você adiciona no teu código.
Então, fica junto com o código.
Você delimita aqueles comentários com alguns caracteres especiais.
Isso depende da linguagem.
Na linguagem Python é por meio de uma hashtag como essa daqui.
E o interpretador, ele simplesmente vai ignorar aqueles comentários com ele for executar o teu código.
Então, os comentários só servem para seres humanos, para as pessoas leerem aquilo e entendeu o programa.
O interpretador ou o compilador, no caso de outras linguagens, ele simplesmente ignoram esses comentários e usam apenas o que está ali fora dos comentários, que é o código de fato.
Então, olha aqui um exemplo de uma documentação da nossa função f, que é x²m1, que a gente viu na aula passada de sobração de funções.
E aqui eu estou documentando essa função por meio de comentários.
Então, o comentário na linguagem Python, uma das maneiras é de se adicionar comentários, é por meio dessas hashtags.
E então, quer dizer, tudo que está à direita dessa hashtag até o final daquela linha vai ser ignorado pelo interpretador.
Então, no caso aqui, essa primeira linha, tudo que está aqui, tudo esse texto que está aqui vai ser ignorado na hora de você rodar esse código lá no teu computador.
Quando ele pula uma linha, vai para a linha de baixo, se você não tiver a hashtag novamente, ele entende aquilo como um código que deve ser executado.
Então, se você quer comentar com várias linhas, você tem que colocar um hashtag em cada linha.
E aí, tudo que está aqui vai ser interpretado como comentário.
Então, eu estou colocando aqui, calcula x²m1, armazenam resultado em res e depois retorno o valor de res.
Então, sempre fazendo essa associação aqui, o que é o código e o que está sendo feito em cada código, em cada linha dessa da edi de instrução.
Caso o comentário ocupi várias linhas, como foi o caso anterior, é possível você, ao invés de usar uma hashtag para cada linha, você pode delimitar esse comentário por meio de três aspas simples ou três aspas duplas seguidas.
Então, aqui estou abrindo uma seção de comentário, tudo que está aqui é comentário, que vai ser excluído pelo interpretador e depois, aqui, eu fecho aquela seção de comentário.
Então, quando você tem textos que devem ocupar mais de uma linha, você pode usar essa syntax de três aspas simples ou três aspas duplas, para abrir depois para fechar aquela seção de comentário.
Bom, é importante, pessoal, a gente saber balancear entre comentários e legibilidade de código.
Tem pessoas que levam 8 ou 80, ou elas não colocam nenhum comentário, isso acaba prejudicando a legibilidade da certa maneira daquele programa, e tem pessoas que documentam até demais, para cada linha ela vai lá e coloca um comentário.
Então, até mesmo para aquelas instruções que não seriam necessárias do comentário, porque a própria instrução já é a auto explicativa, a pessoa vai lá e coloca o comentário.
Então, é importante a gente saber balancear quando se deve adicionar comentários no nosso código ou não.
Às vezes, a gente escolhendo variáveis com nomes mais significativos, isso vai tornar o nosso código mais legível do que ficar adicionando comentários.
Então, se você tem que de certa maneira saber balancear, colocar variáveis com nomes que sejam autosplicativos, trechos de código, que se você acha que são complexos, tem uma lógica muito complex, aí você adiciona comentários.
Tá bom? Bom, uma outra maneira da gente documentar códigos em Parton, é por meio do que a gente chama de Doc Strings, que são documentações que são comentários que você adiciona em funções, que você define.
E depois, essa documentação pode ser acessada por meio da função help, já disponível lá na linguagem Python.
Então, um exemplo já, a pessoa que a gente pode ver, é usar a função help para acessar a documentação das funções que já são predefinidas na linguagem Python.
Então, vamos ver um exemplo aqui no nosso etero.
Então, eu estou aqui no meu interpretador, e eu quero, por exemplo, saber como funciona a função, por exemplo, max.
Então, se eu coloco help entre parênteses ao nome da função max, a gente acessa o Doc Strings dessa função.
Então, olha aqui, aqui eu tenho essa documentação, já disponível para poder acessar.
Se eu quero, por exemplo, saber como funciona a função min.
Também eu tenho uma documentação aqui, já específica para a gente poder visualizar.
E assim, para a maioria das funções.
Então, no caso de funções que foram definidas pelo próprio usuário, se a gente tentar usar essa função help, a gente não vai obter essa documentação.
Então, uma maneira, a gente pode ver entender como a gente cria o Doc Strings de funções que a gente mesmo define, para que depois os usuários daquela função definiu, possam também ter acesso a essa documentação.
Então, vamos ver um exemplo da função f, que a gente já viu, que a gente já definiu ela.
Então, eu tenho aqui a definição da minha função f, f de x.
O resultado vai ser a x², mais 1, e o retorno do resultado dessa função.
Então, essa definição aqui, dessa função, está sendo documentação nenhuma, você pode adicionar alguns comentários aqui.
Por exemplo, eu vou colocar aqui um comentário.
Então, calcula x², mais 1, e depois aqui, eu vou adicionar um outro comentário, que seria retorna o resultado.
Bom, se eu chamar o help dessa função f aqui embaixo, reparem que ele vai me mostrar aqui na tela um texto, que é o texto padrão, e como a gente viu nas outras funções previamente definidas, o texto, a documentação daquela função deveria aparecer aqui embaixo.
Então, aqui, esses comentários não são considerados nessa função help, para considerar alguma coisa para ser exibida por meio da função help, a gente tem que colocar uma estrine de uma maneira um pouco diferente aqui na definição da função, que é adicionar logo a posa, que na primeira linha da definição da função, a gente coloca uma estrine por meio de uma aspas simples, e a gente coloca lá o texto que deveria ser impresso lá na tela.
Então, por exemplo, a gente poderia colocar aqui, exemplo, exemplo, de documentação de funções que será impressa por meio da função help.
Muito bem, agora, olha só o que acontece quando chama help de f.
Então, aquele texto que a gente coloca aqui na primeira linha, a logo após a gente abrir aqui o bloquinho da função, é o que vai ser impresso aqui embaixo para o usuário.
Então, isso, que a gente acabou de fazer, aqui é o uso do help, e é isso, é basicamente essa a video aula da documentação de programas.
Então, a gente viu o que, qual é a importância da documentação de códigos tanto para o usuário como para o programador, e também até para o próprio autor daquele código.
A gente viu duas maneiras diferentes de se adicionar comentários na linguagem Python, e a gente viu que os comentários são a forma de documentação interna de programas, e a gente viu também os docs strings, que é a definição de documentação de funções, tanto aquelas predefinidas, no caso do acesso a essa documentação, como também a criação de documentação de funções que a gente mesmo define.
Então, essa foi a video aula, e a gente vai dar continuidade a nossa aulas nas próximas semanas, e a gente se vê então na próxima oportunidade.