Todos os programas devem ser devidamente documentados através de comentários inseridos em seu código. Os comentários devem estar em pontos estratégicos, presentes em todas as partes onde a execução do programa não seja descrita de forma trivial ou onde o papel de alguma variável não seja de compreensão imediata. Não comente o óbvio.

Para fins administrativos, o programa também deve conter, inicialmente, as seguintes informações, na forma de comentário:

• Nome e RA do(s) autor(es).
• Turma.
• Descrição sucinta do que faz o programa.
• Data em que o programa foi concluído.

Além disto, é muito importante que você se preocupe com a apresentação do código do programa de modo a facilitar sua leitura. As linhas no código devem ser alinhadas de modo a refletir a estrutura do programa. Comandos internos a outro devem ser deslocados à direita como ilustrado no exemplo apresentado mais abaixo.

Conjuntamente com o programa devidamente documentado, deverá ser entregue um relatório. Pretende-se com a cobrança dos relatórios criar em você o hâbito de documentar, ainda que de forma mínima, os programas por você produzidos. Na vida profissional, dificilmente você vai desenvolver software para ser utilizado apenas por você. Para que terceiros possam usar um dado software de forma efetiva, ele deve vir acompanhado de uma documentação técnica adequada.

A documentação também é importante para você próprio. Depois de um certo tempo não lembramos mais de decisões de projeto tomadas quando da confecção de um determinado software. Uma documentação de um software deve registrar estas decisões para facilitar a manutenção deste software. A documentação, portanto, é tão importante quanto o código. Por esta razão, documente bem o que você produz.

Um relatório deverá conter informações e explicações sobre o programa feito. O conteúdo mínimo desejado é:

• Informações de caráter administrativo:
  • Nome e RA do(s) autor(es).
  • Turma.
  • Data de entrega.
• Descrição informal e sucinta do que o programa faz. Esta descrição deverá ser feita, de maneira global, a respeito do programa como um todo sem transcrever literalmente, comando por comando, em Português.
• Explicações sobre como operar o programa, ressaltando quais são as entradas, como serão solicitadas e quais são as saídas esperadas.
• Breve descrição dos algoritmos utilizados na resolução do problema proposto. Aqui cabe novamente a observação acima. Não transcreva para o Português o seu código em Pascal. Abstraia de detalhes de implementação. Produza descrições mais conceituais. Algorimto e programa são coisas distintas. Um algoritmo serve de base para uma implementação de um software sendo que a partir de um algoritmo podemos derivar diversas implementações alternativas.
• As condições de contorno, ou seja, qual é o conjunto de dados de entrada válido para o correto funcionamento do programa. Em que situação o seu programa não funcionaria?
• Relação dos recursos do Turbo Pascal utilizados e não providos pelo Pascal padrão. O objetivo deste item é alertar você sobre um conceito importante na construção de software, denominado

  "portabilidade."

  Como existem diversos ambientes para a execução de programas em Pascal, se não tomarmos cuidado, então um programa que executa em um ambiente não vai executar em outro. O Turbo Pascal representa um ambiente específico. Se usarmos recursos providos pelo Turbo Pascal que não fazem parte do Pascal padrão, então as chances do programa que utiliza estes recursos poder ser executado em outro ambiente são mínimas.
  Para aumentar o grau de portabilidade de um programa, recomenda-se que os recursos peculiares de um ambiente específico sejam confinadas a um conjunto pequeno rotinas bem identificadas. Quando da migração de um software para outro ambiente, então somente estas rotinas dependentes de ambientes precisam ser revistas e reescritas. Se, ao contrário, os recursos peculiares de um ambiente foram utilizados de forma indiscriminada ao longo do código inteiro de um programa, a migração se torna extremamente dificultada.

• Descrição dos erros ocorridos e da(s) estratégia(s) utilizada(s) para o teste do programa. A fase de teste é outra etapa importante no processo de desenvolvimento de software. O processo de concepção de um software deve levar em conta a questão sobre como testar o que foi construído. Obviamente não é possível verificar todas as possibilidades de uso de um software. É necessário, contudo, executar uma série adequada de testes que dê um grau mínimo de confiança de que o artefato de software construído está funcionando de forma aceitável. O ideal seria que pessoas distintas das que tivessem elaborado um programa elaborassem as seqüências de teste baseadas apenas na descrição do que o programa faz e não como o programa resolve o problema em questão.
• Quais foram as dificuldades encontradas.
• O que não foi feito.
• O que foi feito a mais.
• Sugestões sobre possíveis extensões e melhorias do programa.
• Comentários pessoais sobre o que julgar relevante.

• Adira aos padrões de documentação e de confecção de relatórios descrito acima. O grau de aderência a estes padrões tem um peso significativo na correção dos programas solicitados.
• Seje preciso nos seus relatórios. Releia em voz alta o que você escreveu para ver se seu texto faz sentido e se contém os acentos ortográficos nos pontos certos. Verifique se a estruturação de suas frases está correta. Em caso de dúvida sobre como se escreve determinado termo, consulte o dicionário. Reescreva as partes obscuras de seus relatórios.
• Dê especial atenção ao acabamento de seus textos. Um relatório mal acabado dá uma péssima impressão a quem o lê e não inspira confiança no software descrito.
• O texto dos relatórios deve ser de caráter técnico. Não use jargão nem termos em Inglês.

Segue-se um exemplo de um programa cuja apresentação reflete sua estrutura:

001 program Exemplo;
002 {**********************************************************
003 Programa: Contagem de numeros
004 Autor: Jose da Silva (RA 983208)
005 Turma MC111B     Concluido em 14/04/98
006 Descricao:
007   Este programa faz a leitura de n numeros
008   e conta quantos sao positivos, negativos e nulos.
009 ***********************************************************}
010 uses wincrt;
011 const n = 10;
012 var
013   i, numero: integer;
014   positivos, negativos, nulos: integer; {** contadores **}
015 begin
016 {** inicializacao dos contadores **}
017   positivos := 0;
018   negativos := 0;
019   nulos := 0;
020 {** analise dos dados visando determinar o numero de **}
021 {** valores em cada categoria **}
022   writeln('Entre com ',n,' numeros inteiros.');
023   for i := 1 to n do
024   begin
025     write(i:3,') ');
026     read(numero);
027     if numero > 0
028     then
029     begin
030       writeln('O numero ',numero,' e'' maior que zero');
031       positivos := positivos + 1;
032     end
033     else
034       if numero < 0
035       then 
036       begin
037         writeln('O numero ',numero,' e'' menor que zero');
038         negativos := negativos + 1;
039       end
040       else {** neste caso numero = 0 **}
041       begin
042         writeln('O numero ',numero,' e'' nulo');
043         nulos := nulos + 1;
044       end;
045   end;
046 {** impressao dos resultados **}
047   writeln('Na sequencia de ',n,' numeros temos:');
048   writeln('  - Numeros positivos: ',positivos);
049   writeln('  - Numeros negativos: ',negativos);
050   writeln('  - Numeros nulos: ',nulos);
051 end. 

O programa informa quantos números de uma seqüência de n valores inteiros são positivos, quantos são negativos e quantos são zeros.

Na linha

001 program Exemplo;

o programa recebe o nome Exemplo. Nas linhas

002 {**********************************************************
003 Programa: Contagem de numeros
004 Autor: Jose da Silva (RA 983208)
005 Turma MC111B     Concluido em 14/04/98
006 Descricao:
007   Este programa faz a leitura de n numeros
008   e conta quantos sao positivos, negativos e nulos.
009 ***********************************************************}

são fornecidas as informações de caráter administrativo. No ambiente Windows é preciso inserir a linha

010 uses wincrt;

para poder usar os comandos de entrada e saída. Na linha

011 const n = 10;

é declarada uma constante de nome n com valor 10. A constante n indica o tamanho da seqüência de inteiros a ser fornecida pelo usuário. As variáveis do programa são declaradas nas linhas

012 var
013   i, numero: integer;
014   positivos, negativos, nulos: integer; {** contadores **}

sendo

• i: a variável de controle do comando repetitivo da linha 022
• numero: a variável que representa o último número lido da seqüência fornecida pelo usuário
• positivos, negativos, nulos: variáveis utilizadas para contabilizar respectivamente os valores positivos, negativos e zeros da seqüência de entrada.

Os comandos executados pelo programa estão delimitados pelo begin da linha 015 e o end da linha 051. Aos contadores positivos, negativos e nulos é atribuído inicialmente o valor neutro da soma, isto é, o valor zero, nas linhas

017   positivos := 0;
018   negativos := 0;
019   nulos := 0;

Elas representam quantos valores positivos, negativos e zeros já foram lidos num dado instante. Ao iniciarmos a execução do programa, ainda não foi lido nenhum valor. Por esta razão é atribuído o valor zero para indicar que ainda não foi lido nenhum valor em cada uma destas três categorias.

Na linha

022   writeln('Entre com ',n,' numeros inteiros.');

é gerada uma mensagem na tela informando que são esperados n valores inteiros a serem fornecidos pelo usuário.

A seguir temos na linha

023   for i:= 1 to n do

um comando iterativo (também chamado de repetitivo) que executará o comando composto delimitado pelo begin na linha 024 e pelo end da linha 045 n vezes, incrementado a cada iteração a variável de controle em uma unidade. A variável de controle recebe inicialmente o valor 1.

O comando composto que se estende da linha 024 à linha 045 consiste em três comandos. O primeiro, na linha

025     write(i:3,') ');

informa o usuário que valor da seqüência está sendo esperado. O segundo, na linha

026     read(numero);

lê o valor a ser digitado pelo usuário. O processo de leitura se inicia após o usuário digitar o valor e, a seguir, pressionar a tecla ENTER. O terceiro comando consiste de um comando condicional encadeado, que inicia-se na linha

027     if numero > 0

Na linha acima verifica-se, primeiramente, se o valor lido é maior do que zero. Se este for o caso, então

• é gerada uma mensagem correspondente na linha

  030       writeln('O numero ',numero,' e'' maior que zero');
  

• o contador de positivos é incrementado na linha

  031       positivos := positivos + 1;
  

• encerra-se a iteração corrente, já que não há outro comando após o comando condicional encadeado e, se a variável de controle ainda não atingiu o valor n, inicia-se uma nova iteração após o incremento desta variável.

Se a condição da linha 027 foi falsa, então é executado o comando condicional na linha

034       if numero < 0

Neste caso sabemos que o valor lido não é positivo e testamos se ele é negativo. Em caso afirmativo,

• é gerada uma mensagem correspondente na linha

  037         writeln('O numero ',numero,' e'' menor que zero');
  

• é incrementado em uma unidade o contador de valores negativos na linha

  038         negativos := negativos + 1;
  

• e é iniciada uma nova iteração, conforme descrito acima.

Se, por outro lado, a segunda condição também falhou, então é executado o comando composto nas linhas

041       begin
042         writeln('O numero ',numero,' e'' nulo');
043         nulos := nulos + 1;
044       end;

Nesta situação sabemos que o valor lido não é positivo nem negativo e, portanto, só pode ser um zero e

• uma mensagem correspondente é gerada na linha

  042         writeln('O numero ',numero,' e'' nulo');
  

• o contador apropriado é incrementado em uma unidade na linha

  043         nulos := nulos + 1;
  

• e inicia-se uma nova iteração.

Uma vez encerrada a execução do comando iterativo iniciado na linha 023, o resultado computado é gerado pelos comandos nas linhas

047   writeln('Na sequencia de ',n,' numeros temos:');
048   writeln('  - Numeros positivos: ',positivos);
049   writeln('  - Numeros negativos: ',negativos);
050   writeln('  - Numeros nulos: ',nulos);

Relatório

Autor: José da Silva (RA 983208)
Turma: MC111B
Data de Entrega: 14/04/98


Descrição Sucinta do Programa

O programa computa quantos números de uma seqüência de n valores inteiros são positivos, quantos são negativos e quantos são nulos.

Operação do Programa

O usuário deve fornecer os valores conforme solicitados pelo programa. Os valores são solicitados, um por vez, por uma mensagem que indica a posição do valor esperado na seqüência de dados de entrada. Após a digitação o usuário deverá pressionar a tecla ENTER para disparar o processo de leitura. Para processar seqüências de tamanho diferente de 10, o valor da constante n deve ser alterado no código e o código recompilado.

Algoritmo Utilizado

Os números da seqüência de dados fornecidos pelo usuário são consumidos um por vez. A cada dado consumido, é verificado a que categoria (isto é, positivos, negativos e zeros) ele pertence e é efetuada a contabilidade adequada. Ao final deste processo, são apresentados os resultados.

Condições de Contorno

O programa aceita quaisquer valores inteiros no intervalo de inteiros representáveis pelo tipo integer.
Obs: Os extremos deste intervalo variam de acordo com a plataforma onde for executado o programa. No caso do Turbo Pascal no ambiente Windows, este intervalo vai de -32768 até 32767. Dados, que não atendam a sintaxe de inteiros em Pascal, provocarão um "erro fatal" e, conseqüentemente, a interrupção da execução do programa.

Recursos Peculiares do Turbo Pascal

Não foram utilizados recursos desta natureza.

Testes

O programa foi testado com algumas seqüências de valores apenas positivos, apenas negativos, de zeros apenas e com valores mistos. O programa se comportou da maneira esperada.

Dificuldades Encontradas

As mensagens de solicitação de dados ao usuário apresentaram problemas de alinhamento sempre que o número de dígitos da variável i crescia. Para resolver o problema, passou-se a imprimir o valor de i de maneira "formatada" em um campo de 3 posições fixas. O código do programa funciona, portanto, para valores de n até 999. Para valores maiores, a dimensão do campo formatado precisa ser revisto.

Especificação Implementada

O programa implementou todos os requisitos fornecidos na especificação.

Adições

Nenhum recurso não especificado foi implementado

Sugestões

• O programa, ao invés de ter nele embutido o tamanho da seqüência, poderia solicitar este valor ao usuário.
• O programa poderia ser estendido para processar mais de uma seqüência de dados conforme solicitação do usuário.

Comentários

A complexidade do programa foi adequada para exercitar os conceitos iniciais apresentados nas aulas teóricas.

1. Compile e execute o código fonte do programa exemplo acima.
2. Modifique o programa exemplo para que o tamanho da seqüência não seja mais constante, mas seja fornecida pelo usuário.
3. Modifique o programa exemplo para que ele leia dados, enquanto não houver uma indicação explícita, por parte do usuário, de que a seqüência de dados terminou. O tamanho da seqüência de dados, portanto, não é conhecida a priori. De que maneira você poderia identificar a intenção do usuário de concluir a entrada da seqüência de dados?

Obs.: O presente documento foi derivado de um texto originalmente preparado por Allan Francis Dorrington Jr., no âmbito de um projeto de auxílio didático.

http://www.dcc.unicamp.br/~hans/mc111/98s1/document.html