Criando um arquivo README para o seu projeto
Se você já tentou usar o projeto de algum desenvolvedor, sabe o quão complexa essa tarefa pode ser. Quando trabalhamos numa equipe, costumamos chamar a pessoa que desenvolveu para explicar tudo para nós, mas se o desenvolvedor não estiver ao nosso alcance isso não será possível. É por isso que a comunidade adota a prática de criar um arquivo README para todos os projetos desenvolvidos e versionados num Sistema de Controle de Versão (VCS). Esse arquivo, como o próprio nome já diz, é feito para ser lido, pois ele ajudará o usuário interessado no projeto a entender o seu propósito, como usá-lo, como mantê-lo, e diversas outras informações úteis.
Um arquivo README bem escrito é um incrível atrativo para projetos Open Source. Por mais que exija trabalho na sua elaboração, no final vale muito a pena e pode te ajudar inclusive atraindo colaboradores para o seu projeto. No fim das contas, o tempo gasto elaborando esse arquivo é compensado pelo tempo investido pelos colaboradores do seu projeto.
Como escrever?
Agora que você entendeu por que é importante criar um arquivo README para os seus projetos, veremos como devemos escrevê-lo. Vamos assumir que o seu projeto estará hospedado num GitHub, e portanto usará o Git como VCS. Quando você cria um repositório no GitHub, ele mesmo já sugere a criação de um arquivo README. Esse arquivo é criado com o formato Markdown, que é um formato específico para escrever documentação no VCS. Para o nosso exemplo, vamos criar um projeto Java usando o arquétipo quickstart do Maven. O projeto apresentará a seguinte estrutura:
Vamos criar um arquivo chamado README.md no diretório raiz do projeto. Para editar o arquivo, devido ao formato Markdown, é interessante que você use um editor apropriado. Eu particularmente gosto de usar o Atom, pois ele permite que eu visualize uma prévia de como vai ficar o arquivo antes de commitá-lo no repositório. Nesse post não vou entrar em detalhes sobre a sintaxe do Markdown, basicamente o que você precisar está nesse Cheatsheet. Por enquanto, vamos apenas abrir o projeto no Atom e criar o arquivo README:
Com o arquivo README aberto, vamos começar a adicionar cada uma das suas seções.
Nome do Projeto
Essa é a primeira coisa que você precisa escrever no README. Pode parecer fácil mas nomear um projeto é uma arte. Muitos nomes são pensados com elaboradas histórias que fazem sentido para o projeto em diversos níveis. O nome Docker, por exemplo, faz menção a embarcações que transportavam containers de carga, e a partir desse universo diversas terminologias foram adotadas nessa tecnologia, aplicadas ao conceito de virtualização.
Quando for nomear seu projeto, tenha em mente o propósito do mesmo para que ele seja descrito sucintamente no título do projeto. No nosso caso, temos um projeto Java criado a partir de um arquétipo Maven chamado Quickstart. Então, um nome plausível para o projeto é mavenquickstart:
Badges
Se o projeto possuir badges, como as do Travis e Sonar, coloque-as logo abaixo do nome do projeto, para que estejam logo visíveis aos usuários. O trecho adicionado ficará semelhante ao trecho abaixo:
Descrição do projeto
Logo abaixo das badges, adicione uma descrição sucinta do projeto, informando o seu propósito em poucas palavras. A ideia é tentar vender o peixe em no máximo um parágrafo. No nosso caso, o projeto mavenquickstart quer mostrar como é a estrutura de um projeto Maven criado através de um arquétipo quickstart. Então vamos adicionar algo que descreva isso.
Getting started
Aqui você vai informar o que o usuário precisa fazer para poder usar o seu projeto, i.e., os requisitos mínimos e como obtê-los. No nosso exemplo, temos um projeto Maven que roda no JDK10, então vamos precisar do Maven, JDK10, e o Eclipse como IDE para desenvolvimento.
Desenvolvimento
Essa seção explica o que é necessário fazer para evoluir o projeto, ou seja, desenvolver novas funcionalidades no mesmo. No nosso caso, é necessário apenas clonar o projeto do GitHub num diretório de preferência do usuário.
Construção (Build)
Aqui você vai informar os comandos necessários para construir o seu projeto. Como se trata de um projeto Maven, vamos adicionar apenas o comando básico de construção mvn clean install.
Deploy e Publicação
É necessário informar como será disponibilizado o projeto em ambiente produtivo. Esse tópico faz mais sentido para projetos Web, que possuem uma rotina de deploy e publicação em um container. Como o nosso projeto é apenas uma aplicação Java Desktop, não é necessário adicionar esse tópico.
Features
Aqui você vai dizer o que o seu projeto faz, o que ele poderia vir a fazer, basicamente tudo que ele oferece para o usuário. Para o nosso projeto, sabemos que ele pode servir como um projeto Maven inicial para outros desenvolvedores, além de demonstrar como configurar o Maven em um projeto Java.
Configuracão
Nesse tópico, é necessário informar o que é possível configurar no projeto para utilizá-lo. Por exemplo, projetos que recebem entrada de dados podem exigir parâmetros específicos na execução do arquivo jar. No nosso caso, para executar o projeto é necessário importá-lo no Eclipse, já que as bibliotecas não estão sendo por padrão empacotadas no arquivo jar gerado.
Testes
Se o seu projeto possuir testes, é necessário informar como executá-los. No nosso caso, os testes são gerenciados pelo Maven e por isso devem ser executados com o comando mvn test.
Contribuições
Esse tópico é para os seus colaboradores. Eles precisam saber como poderão contribuir e que as suas contribuições serão muito bem-vindas. Se você adota um estilo de codificação, atende a métricas de qualidade, adota uma organização específica de pacotes no projeto, tudo isso deve ser descrito aqui para que o colaborador siga as “regras da casa”. Para o nosso projeto, vamos informar que é obrigatório a presença de testes unitários para cada classe criada com documentação.
Links
Se você precisar adicionar links extras relativos ao projeto em questão, esse é o tópico para isso. No nosso caso, vamos adicionar o endereço do post que deu origem ao projeto.
Licença
Projetos de Open Source precisam ser licenciados corretamente para que os usuários saibam o que podem fazer com ele. A licença correta evita muitos problemas de autoria e por isso deve ser bem pensada para o projeto. Recomendo esse site, que orienta de forma prática a escolha da licença adequada para o seu projeto. No caso do nosso projeto, não adicionarei licença.
Após adicionar todas as seções descritas acima, será possível ver uma preview do arquivo README no Atom clicando com o botão direito no arquivo README.md e selecionando a opção Markdown Preview.
Conclusão
Esse post tentou mostrar a importância de se escrever um arquivo README no seu projeto e como fazê-lo com qualidade. Espero que eu tenha te convencido a adotar essa prática para que façamos o mundo dos desenvolvedores bem melhor.
E se você gostou desse conteúdo e se interessa pelo tema de qualidade de software, dá uma olhada no curso que eu criei sobre testes automatizados com Spring Boot.
Também tenho um canal no Youtube, onde falo sobre desenvolvimento de software, não deixe de conferir, vai ter muito conteúdo bacana por lá! 😉
