Sistemas Embebidos I , Tiago Miguel Dias ISEL, ADEETC - Secção de Eletrónica e Telecomunicações e de Computadores

Transcrição

1 Sistemas Embebidos I Licenciatura em Eng. de Electrónica e Telecomunicações e de Computadores Licenciatura em Engenharia Informática e de Computadores Mestrado em Engenharia de Electrónica e Telecomunicações

2 1. Documentar software A documentação de software é uma parte integrante do processo de desenvolvimento de um programa, cobrindo aspetos relacionados com o seu desenvolvimento e utilização. A documentação exige um planeamento cuidado que visa definir os documentos a produzir, o estabelecimento da sua organização, a escolha da linguagem a utilizar e a seleção das ferramentas a utilizar em cada fase da documentação. A documentação apresenta vantagens a vários níveis: Facilita a manutenção corretiva do programa, reduzindo os custos e o tempo de execução; Facilita a manutenção evolutiva do programa, aumentando a sua durabilidade; Apresenta ao utilizador uma visão geral do software, sem expor detalhes da implementação. Um programa bem documentado deve possuir documentos descrevendo as especificações; um código bem estruturado, que deve estar devidamente comentado pensando em futuros programadores que poderão entrar no meio do projeto; os testes realizados para garantir as funcionalidades que o programa se propõe executar; e as instruções para os utilizadores finais. 2

3 2. Tipos de documentação A documentação de um programa pode ser classificada como Documentação de uso, que é orientada ao utilizador final e visa apresentar a forma de utilização do programa (i.e. manuais de utilização); Documentação técnica, que é orientada aos programadores e destina-se a auxiliar a manutenção corretiva e evolutiva dosoftware. A documentação técnica tem como principal objetivo documentar as partes vagas do projeto/desenvolvimento, ou seja, apresentar o contexto do desenvolvimento, expor as intenções e objetivos do programador, justificar opções de desenvolvimento e indicar opções descartadas. Esta documentação compreende os documentos de projeto (diagramas de fluxo de execução e fluxogramas de processos, organização do código-fonte, dicionários de modelos de dados e de funções, listagem das dependências, apresentação da API, etc), os comentários ao código-fonte e os documentos de teste. A documentação técnica pode ser escrita pelo programador, pelo gestor de projeto ou por um funcionário especializado nesta tarefa. 3

4 3. Documentação técnica :: Código-fonte A documentação do código-fonte é feita inserindo comentários no código. A documentação constrói-se com o código ao invés de ser acrescentada como complemento. Os comentários devem ser introduzidos em pontos estratégicos, em que a interpretação dos troços de código ou a execução do programa não seja trivial. Não se deve comentar o óbvio! Os comentários devem apresentar os objetivos e a justificação para a implementação realizada, atendendo a que o código-fonte já demonstra a implementação. Regras básicas Um comentário de cabeçalho simples no nível do módulo; Comentários para as declarações de dados e tipos significativos; Um comentário de cabeçalho breve por função, descrevendo o seu modo de utilização e qualquer coisa por ela realizada que não seja obvia. Para além disto, é muito importante seguir os padrões recomendados pela linguagem de programação adotada, ter uma boa apresentação do código que facilite a sua leitura (indentação, modularidade, acoplamento e coesão) e utilizar uma nomenclatura significativa e não ambígua para as funções e variáveis. 4

5 4. Produção da documentação técnica :: Código-fonte Para garantir o sincronismo entre o software desenvolvido e a documentação produzida é desejável tratar ambos como dois aspetos do mesmo modelo O modelo é o código-fonte; Uma visualização do modelo pode ser compilada (programa); Outras visualizações do modelo podem ser impressas, vistas na Web, etc (documentação); O objetivo é sempre trabalhar sobre o modelo e ter todas as visualizações atualizadas automaticamente. Usando este modelo, é possível usar ferramentas de documentação automática para produzir documentos que efetivamente explanem o sistema de forma macro, relacionando arquivos que são incluídos em outros, funções, seus parâmetros e retornos, constantes e uma infinidade de informações úteis para melhor se compreender o programa. A documentação produzida por estas ferramentas é extraída dos comentários existentes no código-fonte e, tipicamente, encontra-se organizada em formatos populares (ex.: HTML, CHM, RTF ou PDF). 5

6 5. Ferramenta Doxygen O Doxygen é uma ferramenta de documentação automática, distribuída segundo os termos da GNU General Public License, que pode ser utilizada nos sistemas operativos Unix-like, Mac OS X e Windows. A primeira versão desta ferramenta consistia numa versão antiga da aplicação DOC++, tendo o código da aplicação sido posteriormente reescrito por Dimitri Van Heesch. O Doxygen consegue interpretar as linguagens C, C++, Java, Objective-C, Python, IDL (CORBA e variações da Microsoft), Fortran, VHDL, PHP e C# e extrair os comentários do código-fonte, formatados ou não, para produzir documentação nos formatos HTML, CHM, RTF, PDF, LaTeX, PostScript e man pages. As marcações de documentação podem ser definidas usando os estilos Javadoc e Qt toolkit, entre outros e colocadas ANTES dos elementos que se pretende documentar. No âmbito desta UC será adotado o estilo JavaDoc. 6

7 5. Ferramenta Doxygen :: Configuração Os parâmetros de configuração do Doxygen são definidos num ficheiro de texto. Alguns parâmetros úteis: PROJECT_NAME OUTPUT_LANGUAGE EXTRACT_ALL INPUT FILE_PATTERNS GENERATE_HTML HTML_OUTPUT HTML_HEADER HTML_FOOTER 7

8 5. Ferramenta Doxygen :: Sintaxe JavaDoc Um bloco de documentação na sintaxe do Doxygen difere ligeiramente do padrão da linguagem C, por requerer marcas adicionais que indiquem ao Doxygen que aquela parte do código-fonte deve ser usada para gerar documentação. Usando o estilo Javadoc, um bloco de comentário é escrito seguindo o mesmo estilo da linguagem C, mas começando o comentário com um duplo asterisco /. Para cada item do código-fonte, podem ser utilizados dois tipos de descrição que juntos forma a documentação Descrição breve, que consiste num comentário de uma única linha; Descrição detalhada, que pode ocupar várias linhas e possibilita a utilização de vários comandos para melhorar a qualidade da documentação. Os dois tipos de descrição são opcionais, não se podendo utilizar ambas as descrições para documentar o mesmo item do código-fonte. 8

9 5. Ferramenta Doxygen :: Sintaxe JavaDoc Exemplo de descrição detalhada / Descrição detalhada. / Exemplos de descrição breve / Descrição breve. / / Descrição breve que termina após o primeiro ponto final. Segue-se a descrição detalhada. / (Só se aplica quando a opção JAVADOC_AUTOBRIEF está ativa.) 9

10 5. Ferramenta Doxygen :: Descrição detalhada Para melhorar a qualidade da documentação produzida, no que respeita à sua formatação e ao detalhe da informação disponibilizada, podem definir-se vários campos-chave numa descrição para definir o texto a mostrar na página principal da para definir o nome do para definir o nome do autor responsável pelo bloco de para definir a versão do para definir a data de para indicar a data da primeira para definir um comentário para definir uma para definir o(s) parâmetro(s) das para definir o retorno das para definir typedef, para definir tipos de dados. 10

11 5. Ferramenta Doxygen :: Exemplo de Tiago M LICENSE Este ficheiro é distribuído na esperança de que possa ser útil na produção de documentação usando a ferramenta Doxygen, mas garante isso per DESCRIPTION Ficheiro exemplo da utilização da ferramenta Doxygen. / Função de exemplo Esta função tem como objetivo exemplificar o uso do firstparam Serve como primeiro parâmetro da anotherparam O outro parâmetro da Descrição dos valores retornados pela função. / int FuncaoDeExemplo(int firstparam, int anotherparam) { //... } 11

12 5. Ferramenta Doxygen :: Utilização Para criar a documentação associada a um projeto deve seguir-se a seguinte metodologia Documentar o código-fonte usando a sintaxe do Doxygen Gerar um ficheiro de configuração para o projeto Para gerar o ficheiro de configuração deve usar-se o comando doxygen -g <config_file> Executar o Doxygen com base na informação expressa no ficheiro de configuração definido Para gerar a documentação deve usar-se o comando doxygen <config_file> 12