NOME

perlstyle - Guia de Estilos de Perl

DESCRIÇÃO

Cada programador terá, naturalmente, suas próprias preferências quanto à formatação de código, mas existem algumas normas que tornarão seus programas mais fáceis de serem lidos, entendidos e mantidos.

O mais importante é executar seus programas usando sempre a flag -w. Você pode desativá-la explicitamente em trechos de código usando o pragma no warnings ou através da variável $^W se desejar. Você deve sempre executar seu código usando o pragma use strict ou saber a razão para não fazê-lo. Os pragmas use sigtrap e use diagnostics podem também ser úteis.

Em relação à estética do código, a única coisa com a qual o Larry realmente se importa é que o fecha-chaves de um BLOCO com mais de uma linha esteja alinhado com o comando que deu início ao bloco. Fora isso, ele tem outras preferências não tão rígidas:

• Identação em 4 colunas.

• Abra chaves na mesma linha do comando, se possível. Senão, alinhe-a.

• Dê espaco antes de abrir chaves em um bloco com mais de uma linha.

• Blocos de uma linha podem ser colocados em uma única linha, incluindo abre-chaves e fecha-chaves.

• Nenhum espaço antes do ponto-e-vírgula.

• Omita ponto-e-vírgula em blocos pequenos de uma linha.

• Coloque espaços antes e depois da maioria dos operadores.

• Coloque espaços antes e depois de índices complexos (dentro de colchetes).

• Coloque linhas em branco entre pedaços de código que façam coisas diferentes.

• Coloque o else na linha abaixo do fecha-chaves do if.

  Exemplo:

      if (...) {
          ...
      }
      else {
          ...
      }

• Não use espaços entre o nome de uma função e o parêntese.

• Espaços depois de cada vírgula.

• Quebre linhas muito longas depois de um operador (exceto "and" e "or").

• Espacos depois do último parêntese fechado na mesma linha.

• Alinhe verticalmente os items correspondentes.

• Omita pontuação redundante desde que não afete a clareza do código.

Larry tem seus motivos para cada uma destas normas, mas não pede que todos trabalhem da mesma forma que ele.

Abaixo encontram-se algumas outras questões sobre estilos a serem considerados:

• Só porque eu POSSO fazer algo de um modo em particular não quer dizer que eu DEVA fazê-lo dessa forma. Perl foi projetado para te deixar fazer tudo de muitas maneiras diferentes, então considere escolher a mais legível delas. Por exemplo

      open(FOO, $foo) || die "Erro ao abrir $foo: $!";

  é melhor que

      die "Erro ao abrir $foo: $!" unless open(FOO, $foo);

  porque a segunda forma esconde o objetivo da declaração em um modificador. Por outro lado

      print "Iniciando análise\n" if $verbose;

  é melhor que

      $verbose && print "Iniciando análise\n";

  porque a questão principal não é se o usuário digitou -v ou não.

  Similarmente, só porque um operador permite que você assuma argumentos padrão não quer dizer que voce tenha que usar tais padrões. Os argumentos padrão estão lá para programadores preguiçosos de sistemas escrevendo soluções rápidas que serão executadas somente uma vez. Se você quer que seu programa seja legível, considere fornecer explicitamente os argumentos.

  Dentro dessa mesma linha, só porque você PODE omitir parênteses em muitos lugares não que dizer que você deva:

      return print reverse sort num values %array;
      return print(reverse(sort num (values(%array))));

  Quando em dúvida, coloque parênteses. No mínimo irá permitir que as pessoas brinquem com a tecla % no vi.

  Mesmo que não tenha dúvidas, considere a saúde mental da pessoa que irá manter seu código depois de você, e que provavelmente colocará os parênteses no lugar errado.

• Não faça contorcionismos para sair de um loop no seu início ou final, quando o Perl possui o operador last para que você possa sair no meio do mesmo. Tire um pouco da identação se quiser deixá-lo mais visível:

      LINE:
      for (;;) {
          statements;
        last LINE if $foo;
          next LINE if /^#/;
          statements;
      }

• Não tenha medo de usar rótulos em laços (loops) -- eles existem para aumentar a legibilidade assim como para permitir vários níveis de saída de laços. Veja o exemplo anterior.

• Evite usar grep() (ou map()) ou `backticks` em contexto vazio (void), isto é, quando você descarta o valor de retorno. Todas estas funções possuem valores de retorno, então use-os. Do contrario, use um laço foreach() ou a função system().

• Por questão de portabilidade, quando usar funcionalidades que podem não estar implementadas em todos os sistemas, teste a construção em um eval para verificar se existe falha. Se souber a versão ou patchlevel em que uma funcionalidade foi implementada, você pode testar a variável especial $] ($PERL_VERSION se usar o pragma English) para saber a funcionalidade estará lá. O módulo Config também permite a verificação de valores determinados pelo programa Configure quando o Perl foi instalado.

• Escolha identificadores claros. Se você não sabe o que claro significa, você tem um problema.

• Enquanto identificadores curtos como $gotit provavelmente servem, use o caractere de sublinhado para separar palavras em identificadores mais longos. Costuma ser mais fácil ler $nomes_de_variaveis_assim do que $NomesDeVariaveisAssim, especialmente para pessoas que não falam nativamente o idioma em que o identificador foi escrito. Também trata-se de uma regra simples e que funciona consistentemente para NOMES_DE_VARIAVEIS_ASSIM.

  Nomes de pacotes são uma exceção a essa regra. Perl informalmente reserva nomes com letras minúsculas para módulos "pragma" como integer e strict. Outros módulos devem iniciar seu nome com letra maiúscula e misturar maiúsculas e minúsculas, mas provavelmente sem sublinhados devido à limitações impostas pela representação dos nomes de modulos como arquivos em apenas alguns bytes em sistemas de arquivos primitivos.

• Você pode achar útil usar maiúsculas e minúsculas para indicar o escopo ou natureza de uma variável. Por exemplo:

    $LETRAS_MAISCULAS_AQUI      somente constantes (cuidado para não
                                colidir com variaveis do Perl!)
    $Algumas_Maiusculas_Aqui    globais/estáticas em seu pacote
    $sem_maiusculas_aqui        variáveis C<my()> ou C<local()> de
                                escopo de funções

  Nomes de funções ou métodos parecem visualmente melhores se completamente em letras minúsculas. Ex: $obj->as_string().

  Você pode começar identificadores de variáveis e funções com um caractere de sublinhado para indicar que ela não deve ser usada fora do pacote onde foi definida.

• Se você tiver uma expressão regular cabeluda, use o modificador /x e ponha alguns espaços em branco para melhorar sua legibilidade. Não use "/" ou "\" como delimitadores quando sua expressão regular tiver "/" ou "\" ela própria.

• Utilize os operadores and e or para evitar colocar muitos parênteses em operadores de listas e reduzir a incidência de operadores de pontuação como && e ||. Chame suas subrotinas como se fossem funções ou operadores de lista para evitar o excesso de "&" e parênteses.

• Use here documents em vez de vários print() seguidos.

• Alinhe elementos correspondentes verticalmente, especialmente se for longo demais para caber em uma única linha.

      $IDX = $ST_MTIME;
      $IDX = $ST_ATIME       if $opt_u;
      $IDX = $ST_CTIME       if $opt_c;
      $IDX = $ST_SIZE        if $opt_s;
  
      mkdir $tmpdir, 0700 or die "can't mkdir $tmpdir: $!";
      chdir($tmpdir)      or die "can't chdir $tmpdir: $!";
      mkdir 'tmp',   0777 or die "can't mkdir $tmpdir/tmp: $!";

• Sempre verifique o valor de retorno de uma chamada ao sistema (system call). Boas mensagens de erro devem ir para o STDERR, incluir o programa que causou o problema, qual chamada ao sistema e com quais argumentos, e (MUITO IMPORTANTE) deve conter a mensagem padrão do sistema para o que deu errado. Aqui apresentamos um exemplo simples mas suficiente:

      opendir(D, $dir)     or die "can't opendir $dir: $!";

• Alinhe suas transliterações sempre que isso fizer sentido.

      tr [abc]
         [xyz];

• Pense em reusabilidade. Por que desperdiçar massa cinzenta em um código pra ser executado apenas uma vez quando você pode precisar fazer assim no futuro? Considere generalizar seu código. Considere escrever um módulo ou classe de objetos. Considere em fazer com que seu código execute limpo com use strict e <use warnings> (ou -w) ativos. Considere distribuir seu código. Considere mudar o modo como vê o mundo. Considere... ah, deixa pra lá.

• Procure documentar seu código e usar a formatação Pod de forma consistente. Aqui estão algumas convenções esperadas:

  • use C<> para nomes de funções, variáveis ou módulos (and de forma mais geral qualquer coisa que possa ser considerada parte de código, como handles de arquivos ou valores específicos). Note que nomes de funções costumam ser mais legíveis com parênteses após o nome, isto é, funcao().

  • use B<> para nomes de comandos como cat ou grep.

  • use F<> or C<> para nomes de arquivos. F<> deverá ser o único código Pod para nomes de arquivos, mas como muitos formatadores de Pod renderizam como itálico, caminhos de diretórios com "/" e "\" podem ficar menos legíveis, e renderizam melhor com C<>.

• Seja consistente.

• Seja uma pessoa boa.

TRADUÇÃO

João Ribeiro da Silva

Breno G. de Oliveira