Por quê deveria me preocupar em documentar o meu software?
Documentar o software é uma tarefa que muitas vezes é negligenciada mesmo sendo algo que agrega um valor absurdo para qualquer projeto. Existem várias razões para se documentar um software, mas a principal é que ela permite que outras pessoas possam entender o que o software faz e como ele funciona. Até parece um absurdo absurdo ter que explicar esses motivos, mas acredito que o óbvio às vezes precisa ser dito. 😁
Existem documentações que são mais técnicas, como a documentação de API, e outras que são mais voltadas para o usuário final, como a documentação de usuário. Mas, independente disso, ter uma documentação no final das contas é o que importa. Não, você entendeu e sim, precisa ser no mínimo “entendivel”.
Documentação de software
O foco aqui, será a documentação de software em si e pensando um pouco sobre a pergunta inicial, a resposta parece óbvia, então, por quê é muito comum encontrarmos softwares com pouca, ou até sem nenhuma, documentação? Os motivos que levam as pessoas a subestimar a importância de documentar o software podem ser os mais variados. Desde o simples fato de como a equipe/empresa encara seus processos até o “há, meu código é tão legível que não precisa de documentação” e não estou falando isso porque sempre documentei o meu código, se é que me entende. 😎
O código de hoje é o legado de amanhã
Já parou pra pensar nisso? Algo que é bastante comum na vida de quem escreve software, ou quem lida com tecnologia diariamente é que as coisas acontecem(evoluem) com uma velocidade incrível. Como se já não bastasse ter que lidar com várias tecnologias, regras complexas e etc… Ainda precisamos fazer isso com rapidez e qualidade e se pararmos pra pensar é um baita desafio e demanda muita energia.
O outro lado do que acabei de falar é o fato de que tecnologias às vezes são descontinuadas, as regras de negócio mudam e sim as pessoas hoje trabalham em um lugar e amanhã não. Então, como fazer para contornar todas essas coisas? É o que vou tentar passar aqui.
Da “especialização” de responsabilidades e os cuidados
Pessoas entram e saem de empresas, e com elas vão conhecimentos e experiências. Mas, o quê acontece quando uma pessoa sai da empresa e deixa um conhecimento importante para trás? Ou quando uma pessoa entra na empresa e não tem acesso a esse conhecimento?
A especialização de responsabilidades é um conceito que pode ser aplicado em diversas áreas, mas que é bastante comum em empresas que trabalham com desenvolvimento de software. A ideia é que cada pessoa(time) tenha uma responsabilidade específica e que essas pessoas sejam as únicas responsáveis por lidar com as tarefas daquele domínio. Agora imagine o que acontece quando seu negócio ou uma área importante do seu negócio é dependente destes “conhecimento de domínio” e a maior parte está centralizada em uma pessoa? Nem preciso te dizer que o problema pode evoluir rápido se essa pessoa decide sair da empresa do dia pra noite. Neste cenário, o que geralmente se vê, é uma correria para que uma nova pessoa assuma rápido e consiga reter o máximo de informações possíveis sobre aquele contexto que o qual sua empresa depende tanto.
São muitos erros cometidos de forma sucessiva e talvez alguém agora pense que seria uma boa documentar tudo e claro você não faz isso do dia pra noite. Até pode tentar, mas esse será mas esse será um bloco de concreto enorme a mais para carregar com tantas coisas acontecendo.
A documentação é a chave
Existem várias maneiras, técnicas e ferramentas para documentar o seu software e cada uma delas tem propósitos. Se você ainda não utiliza nenhuma ferramenta ou não sabe por onde começar, bem, espero que este post te ajude. Porém, a dica que eu já posso te dar de cara é: Comece!
- Como? Comentários no código, arquivo markdown, google docs ou até mesmo em um arquivo de texto. O importante é que você comece a fazer isso o quanto antes.
YARD
Atualmente, eu uso mais uma ferramenta chamada YARD. Ela é amplamente usada na comunidade Ruby e já existe há um bom tempo, então, neste post usá-la nos exemplos. No geral, o YARD te permite gerar uma documentação consistente e utilizável e que pode ser exportada para vários formatos com muita facilidade.
Tirei essa foto do celular durante um periodo de férias em Agosto de 2022 - Viçosa no Ceará.
Instalando
Para instalar o YARD você irá precisar do Ruby. Então basta digitar o seguinte comando no terminal:
$ gem install yard
Usando
Existem algumas maneiras de usar o YARD. A primeira é via linha de comando e a segunda é a tarefa Rake.
O YARD vem empacotado com um executável chamado yard que te permite fazer algumas coisas incluindo a geração de documentação, subir um servidor local para visualizar a documentação e assim por diante. Para visualizar uma lista de comandos YARD disponíveis, digite:
$ yard --help
Os plug-ins também podem adicionar comandos ao yard executável para fornecer funcionalidades extras. Mas aqui não irei falar sobre eles. Apenas saiba que é possível estender as funcionalidades e que elas existem.
DSL
DSL é a forma como você interage com o YARD. Neste ponto, o YARD é bem simples de usar. Neste contexto, o que usaremos para documentar são as tags na forma de comentário e são declaradas, geralmente, acima do seu código é muito simples. A seguir eu irei listar algumas tags e explicar um pouco na prática como você irá aplicar. A dica aqui é: Não tente memorizar tudo de cara, não se preocupe, você irá aprender rapidinho se incluir esta etapa em sua rotina.
Documentando Classes
A notícia boa é que se você começou a fazer pelas dicas anteriores, onde, você já “começou” documentando, seja no código, em arquivo markdown ou em outro lugar que seja, você pode começar trazendo para o topo da sua classe começando a descrever o que ela faz. Ex.
# This class represents a person
#
class Person
end
Perceba que não utilizamos nenhuma tag, mas já é um bom começo. Agora, vamos adicionar algumas tags para descrever melhor a classe.
# This class represents a Person
#
class Person
# @return [String] the person's name
attr_accessor :name
# @return [Integer] the person's age
attr_accessor :age
end
Agora, eu utilizei a @return tag para descrever o que cada método faz. A tag @return é usada para descrever o que um método retorna. Você pode usar a @return tag para descrever o tipo de retorno de um método. Por exemplo:
# This class represents a person
#
class Person
# @return [String] the person's name
attr_accessor :name
# @return [Integer] the person's age
attr_accessor :age
# @return [Person] a new person with the given name and age
def self.create(name, age)
new(name, age)
end
end
Agora, eu utilizei a tag @return para descrever o que o método create retorna. Neste caso ele irá retornar uma instância de Person com nome e idade que foram passadas. Já é um bom começo. Agora antes de ler o código já sei exatamente o que ele irá retornar. Isso pode ajudar bastante no processo de depuração, acredite.
Ok, mas eu estou recebendo dois argumentos, seria uma boa ideia documentar isso também, não é mesmo? Para tal, você pode usar a @param tag para descrever os parâmetros. Por exemplo:
# This class represents a person
#
class Person
# @return [String] the person's name
attr_accessor :name
# @return [Integer] the person's age
attr_accessor :age
# @param [String] name the person's name
# @param [Integer] age the person's age
# @return [Person] a new person with the given name and age
def self.create(name, age)
new(name, age)
end
end
WoW, agora eu sei exatamente o que esperar quando eu chamar o método create. Eu sei que ele espera dois argumentos, um nome, que é do tipo String, e uma idade, que é do tipo Integer, também sei que ele irá retornar uma nova instância de Person com o nome e a idade que eu passei. Isso é muito útil.
Mas e se não está claro o que o método faz? Você ainda pode usar a @note e a @example tags para adicionar mais detalhes sobre o que o método faz. Por exemplo:
# This class represents a person
#
class Person
# @return [String] the person's name
attr_accessor :name
# @return [Integer] the person's age
attr_accessor :age
# @param [String] name the person's name
# @param [Integer] age the person's age
# @return [Person] a new person with the given name and age
# @note This method is used to create a new person
# @example
# Person.create('John Doe', 30)
def self.create(name, age)
new(name, age)
end
end
Perceba que eu adicionei a @note tag para descrever o que o método create faz. Eu também adicionei a @example tag para mostrar um exemplo de como usar o método create. Agora, se alguém ler a documentação, ela saberá exatamente o que o método create faz e como usá-lo.
Até aqui, eu mostrei como documentar classes e métodos, mas você pode usar as mesmas tags para documentar módulos, constantes, atributos de instância, atributos de classe de leitura, atributos de classe de escrita e atributos de classe de leitura e escrita, ou seja, com o Yard você consegue fazer muito com o pouco.
Tá, mas onde eu vejo essa documentação?
A documentação gerada pelo YARD é gerada em HTML por padrão. Para visualizá-la, antes, você precisa usar o comando que irá fazer a leitura do seu código e gerar a documentação logo em seguida.
$ yard doc .
Após a execução do comando, você pode visualizar a documentação gerada abrindo o arquivo doc/index.html em seu navegador ou você pode subir o servidor embutido que pode ser usado para servir a documentação gerada. Você pode fazer isso através do comando:
$ yard server
O resultado final deve se parece com isso:
Simples, sem muito esforço e com um resultado muito bom. A documentação gerada pelo YARD é muito bonita e fácil de usar. Olha quantos detalhes você é capaz de obter.
Conclusão
O YARD é uma ferramenta muito poderosa e vai te ajudar a prevenir todas as dores que mencionei no início deste post. Lembrando que a dica mais valiosa aqui não é o código e saber como fazer para usar determinada ferramenta e sim a visão de futuro e entender o impacto que essa medidas tem dentro da sua empresa, projeto e por último mas não menos importante, dentro do seu time. Afinal, é seu “eu” do futuro que irá precisar, em algum momento, voltar no código e entender sem perder muito cabelo para entender o que acontece alí.
Agora não tem desculpa para não documentar o seu código. 😁🥳