Comentários em funções

Existe uma última melhoria importante que necessitamos fazer na função future_value. De- vemos comentar o seu comportamento. Comentários são para leitores humanos, e não para com-

piladores, e não existe um padrão universal para o leiaute de um comentário de função. Neste livro vamos usar sempre o seguinte leiaute:

/**

Calcular o valor de um investimento com taxa de juros compostos @param initial_balance o valor inicial de um investimento @param p a taxa de juro por período, em percentagem

@param n a quantidade de períodos em que o investimento é mantido @return o saldo após n períodos

*/

double future_value(double initial_balance, double p, int n) {

double b = initial_balance * pow(1 + p / 100, n); return b;

}

Puxa! O comentário é mais longo do que a função! Realmente ele é, mas isso é irrelevante. Ti- vemos sorte que esta função particular foi fácil de computar. O comentário da função não apenas documenta a implementação, mas a idéia — enfim, uma propriedade mais valiosa.

De acordo com o estilo de documentação usado neste livro, cada função (exceto a main) deve ter um comentário. A primeira parte do comentário é uma breve explicação da função. Após, colo- que uma entrada @parampara cada parâmetro, e uma entrada @returnpara descrever o valor de retorno. Como você verá mais adiante, algumas funções não possuem parâmetros ou valores de re- torno. Para estas funções, @paramou@returnpode ser omitido.

Este estilo particular de documentação foi emprestado da linguagem de programação Java — ele é freqüentemente chamado de estilo javadoc. Existem várias ferramentas disponíveis que pro- cessam arquivos C++ e extraem páginas HTML contendo um conjunto de comentários com hyper-

links — ver Figura 4. O site da Web associado a este livro contém instruções para fazer download

e usar uma destas ferramentas.

Ocasionalmente você vai achar tolice escrever os comentários de documentação. Isto é espe- cialmente verdadeiro para funções de uso geral:

/**

Calcula o máximo de dois inteiros. @param x um inteiro

@param y outro inteiro

@return a maior das duas entradas */

int max(int x, int y) { if (x > y) return x; else return y; }

Deveria ser perfeitamente claro que maxcalcula o máximo e é óbvio que a função recebe dois inteiros xe y. De fato, neste caso, o comentário é algo excessivo. Apesar disso, nós sem- pre recomendamos fortemente a escrita de comentários para cada função. É fácil gastar mais tempo ponderando se o comentário é demasiado trivial para ser escrito do que leva apenas pa- ra escrevê-lo. Em programação prática, funções muito simples são raras. Não há problema al- gum em ter uma função trivial super comentada, enquanto que ter uma função complicada sem nenhum comentário pode causar grande pesar para futuros programadores de manutenção. A experiência prática tem demonstrado que comentários para variáveis individuais raramente são úteis, desde que os nomes escolhidos para estas variáveis sejam autodocumentáveis. Funções criam uma divisão lógica muito importante em um programa C++, e uma grande parte do es- forço de documentação deve ser concentrada em explicar o funcionamento de seu comporta- mento como caixa-preta.

É sempre uma boa idéia escrever primeiro o comentário da função, antes de escrever o código da função. Isto é um excelente teste para ver se você entendeu firmemente o que você necessita pa-

ra programar. Se você não pode explicar as entradas e saídas de uma função, ainda não está apto a

escrevê-la.

Dica de Produtividade

5.2

Pesquisa e Substituição Globais

Suponha que você escolheu um nome infeliz para uma função, digamos fvem vez de futu- re_value, e você lamenta a sua escolha. Naturalmente, você pode localizar todas as ocorrências de fvem seu código e substituí-las manualmente. Entretanto, a maioria dos editores de programas possui um comando para pesquisar automaticamente todas as ocorrências de fve substituí-las por future_value.

Você precisa especificar alguns detalhes para a pesquisa.

• Você quer que sua pesquisa ignore maiúsculas e minúsculas? Isto é, FVdeve ser considerado igual a fv? Em C++ você geralmente não quer isso.

• Você quer pesquisar somente palavras inteiras? Se não, o fvem Golfvilleé tam- bém uma combinação. Em C++, você geralmente deseja pesquisar palavras inteiras. • Isto é uma pesquisa com expressões regulares? Não, porém expressões regulares po- dem servir para pesquisas ainda mais poderosas — ver Dica de Produtividade 5.3.

Figura 4

• Você quer confirmar cada substituição, ou simplesmente ir em frente e substituir to- das as combinações? Confirme as primeiras três ou quatro combinações e veja se es- tá funcionando como esperado, e ordene ir em frente para substituir o restante (a pro- pósito, uma substituição global significa substituir todas as ocorrências no documen- to). Bons editores de texto podem desfazer uma substituição global que foi feita erro- neamente. Veja se o seu faz ou não.

• Você quer que a pesquisa seja feita a partir do cursor até o fim do arquivo do pro- grama, ou deve ser feita no texto atualmente selecionado? Restringir a substituição a uma porção do arquivo pode ser bastante útil, mas neste exemplo você pode que- rer posicionar o cursor no início do arquivo e fazer a substituição até o final do ar- quivo.

Nem todos os editores possuem todas estas opções. Você deve investigar o que o seu editor oferece.

Dica de Produtividade

5.3

Expressões Regulares

Expressões regulares descrevem padrões de caracteres. Por exemplo, números possuem uma for- ma simples. Eles contém um ou mais dígitos. Uma expressão regular para descrever números é [0-9]+. O conjunto [0-9]indica qualquer dígito entre 0 e 9, e o +significa “um ou mais”.

Para que serve isto? Diversos programas utilitários usam expressões regulares para localizar combinações de texto. Também os comandos de pesquisa de alguns editores de programas enten- dem expressões regulares. O programa mais popular que usa expressões regulares é grep(que significa “global regular expression print”). Você pode executar grepa partir de um prompt de comando ou de dentro de alguns ambientes de compilação. Ele necessita uma expressão regular e um ou mais arquivos para pesquisar. Quando o grepé executado, ele exibe um conjunto de linhas que combinam com a expressão regular.

Suponha que você quer pesquisar todos os números mágicos (ver Dica de Qualidade 2.3) em um arquivo. O comando

grep [0-9]+ homework.cpp

lista todas as linhas do arquivohomework.cppque contêm seqüências de dígitos. Isso não é ter- rivelmente útil; linhas com nomes de variáveis como x1serão listadas. Você quer seqüências de dí- gitos que não seguem imediatamente letras:

grep [^A-Za-z][0-9]+ homework.cpp

O conjunto [^A-Za-z] indica quaisquer caracteres que não estão entre A e Z ou entre a e z. Isso funciona muito melhor, e mostra apenas linhas que contém números verdadeiros.

Existe um espantoso número de símbolos (algumas vezes chamados curingas) com significados especiais na sintaxe de uma expressão regular, e infelizmente programas diferentes usam diferentes estilos de expressões regulares. É melhor consultar a documentação do programa para ver detalhes.