Docstrings são comumente strings envolvidas por três aspas, também conhecidas por strings multi-linha, pois as três aspas permitem que a string abranja mais de uma linha.
Uma docstring contém a informação essencial que alguém precisaria para usar essa função. Ela explica concisamente o que a função faz (sem entrar em detalhes de como ela faz). Ela explica que efeito cada parâmetro tem na execução da função e qual tipo cada parâmetro deve ser (se não é óbvio).
Escrever esse tipo de documentação é uma parte importante do design de interface. Uma interface bem projetada deve ser simples de explicar; se você encontra dificuldade em explicar uma de sua funções, talvez sua interface possa ser melhorada.
Uma interface é como um contrato entre a função e quem a chama. Quem chama concorda em fornecer certos parâmetros e a função concorda em fazer um certo trabalho.
Por exemplo, polilinha requer quatro argumentos: t tem que ser uma tartaruga; n tem que ser um inteiro; com deve ser um número positivo; e ângulo tem que ser um número, que assume-se ser uma medida em graus.
Esses requerimentos são chamados de precondições pois eles deveriam ser verdadeiros antes que a função execute. Inversamente, condições no final da função são chamadas de pós-condições. Pós-condições incluem o efeito desejado da função (como desenhar segmentos de linha) e qualquer efeito colateral (como mover a tartaruga ou fazer outra mudança).
precondições são de responsabilidade de quem chama a função. Se quem chama viola uma precondição (propriamente documentada!) e a função não funciona adequadamente, o bug está em quem chamou, e não na função.
Se as precondições são satisfeitas e as pós-condições não, então o bug está na função. Se as suas pré- e pós-condições forem claras, elas podem ajudar na hora de depurar.
O processo de substituir algo desnecessariamente específico (como um número) por algo mais adequadamente irrestrito (como uma variável ou parâmetro).
Uma descrição de como usar uma função, incluindo o nome, as descrições dos argumentos e o valor de retorno.