Artigos Mobile Aprenda a documentar seus projetos em Objective-C - Revista Mobile Magazine 48
Artigo do tipo Tutorial
Recursos especiais neste artigo:
Conteúdo sobre boas práticas.

Documentação e Objective-C
A documentação do código fonte é cada vez mais considerada uma atividade essencial em projetos de desenvolvimento de software. Dentre seus benefícios, ela força o desenvolvedor a explicitar o objetivo das classes e métodos que estão sendo implementados, além de facilitar (e muito) atividades futuras de manutenção. Sabe-se que estas atividades muitas vezes não são desempenhadas pelo próprio desenvolvedor que criou um determinado método. Note então o quão importante é manter um código bem documentado, trabalhar em código de terceiros é complexo e propenso a erros, e uma das formas de minimizar estes problemas é justamente com um código bem documentado.

Neste artigo veremos a importância da documentação no desenvolvimento de sistemas, fatores que diminuem sua prática e como evitá-los. Além disso, será apresentado o framework de geração de documentação através de comentários de código appledoc com um guia de utilização.

O framework appledoc permite que seja gerada documentação detalhada de sistemas desenvolvidos em Objective-C utilizando o mesmo design de bibliotecas de documentação da Apple. A documentação é escrita na forma de comentários de código que são parseados gerando fontes em html estáticos que podem ser colocados na nuvem para consulta remota.

Em que situação o tema é útil
A documento do código fonte de um projeto é muitas vezes negligenciada. Contudo, ela pode ser considerada um item importante para sucesso do projeto. Alguns de seus principais benefícios é facilitar o entendimento futuro das funcionalidades implementadas no projeto. Isto é essencial principalmente em atividades de manutenção de software quando, muitas vezes, o responsável por efetuar a manutenção é diferente do responsável pelo seu desenvolvimento.

A conscientização dos fatores que prejudicam a documentação de códigos-fontes e como contorná-los de forma a deixar claro na mente de jovens desenvolvedores os seus benefícios é também um dos benefícios da leitura deste artigo.

Num ambiente de programação ágil, usando metodologias como Scrum, Agile e Lean, nem sempre há tempo de documentar os códigos-fonte. Afinal, pragmáticos como são os desenvolvedores, por que perderiam tempo se a documentação não será compilada, não fará a menor diferença na execução do programa e demanda uma fatia considerável de tempo do desenvolvedor? Mas independentemente disso tudo, documentação faz falta. Muita falta.

Quem está familiarizado, sabe que no ritmo acelerado das startups tudo o que é feito é “para ontem” e nem sempre há tempo para aplicar algumas das boas práticas de programação que não são fundamentais ao bom funcionamento e à agilidade do código. Diversas vezes deixa-se de testar formalmente classes e métodos em função do prazo virtualmente nulo que é passado. É fácil descobrir desenvolvedores virando noite para que consigam lançar no dia seguinte aquela funcionalidade chave. Testar? Documentar? Revisar? Tantas coisas para fazer num tempo tão curto!

Essa é a realidade de muitos jovens desenvolvedores, que entram nesse ambiente competitivo em busca do sonho de abrir a própria empresa. A obrigação de satisfazer potenciais investidores, a cobrança por entregas e as necessidades do cliente frequentemente ofuscam técnicas que melhoram a experiência de desenvolvimento e manutenção, porém que não são consideradas primordiais para o funcionamento de uma aplicação. Quantas vezes não se volta a um código não documentado feito há menos de dois meses antes e pensa-se “o que esse loop faz?”, ou então “por que essa classe está aqui e não ali?” Obviamente, quando aquelas linhas de código foram escritas, tudo fazia total sentido, porém, assim que aqueles ifs e fors saíram da mente consciente, seu significado, há muito, já havia deixado de ser importante. Afinal, como diz o provérbio chinês, “a tinta é melhor que a memória”.

Então, documentemos. Na verdade, documentar é como comer legumes: ninguém realmente gosta, mas fazemos o sacrifício pois esperamos que, no final, valha o resultado. A documentação comprovadamente facilita as nossas vidas. Ao contrário do que se pensa, o tempo gasto documentando o trabalho de um dia é razoavelmente irrelevante e o benefício que temos em troca, definitivamente compensa esse trabalho.

...
Quer ler esse conteúdo completo? Tenha acesso completo