# $Id$

=head1 NOME

O Guid de brian para Resolver Qualquer Problema em Perl

=head1 SYNOPSIS

Siga este guia simples e salve sua sanidade mental

=head1 DESCRIÇÃO

=head2 Minha Filosofia de Depuração

Eu acredito em três coisas:

=over 4

=item Não é nada pessoal

Esqueça quem é o "dono" do código. Você pode pensar em si mesmo
como um artista, mas mesmo os velhos Mestres produzem um monte de
porcaria. O código de todo mundo é poracria, o que significa que o
meu código é porcaria e que o seu código é porcaria. Aprenda a amar
isso. Quando você tem um problema, seu primeiro pensamento deve ser
"tem algo errado com a porcaria do meu código". Isso significa que
você não pode culpar perl. Não é nada pessoal.

Esqueça o modo como B<você> faz as coisas. Se a maneira como você
fez as coisas funcionasse, você não estaria lendo isto. Isso não é
uma coisa ruim. É só a hora de evoluir. Todos já passamos por isso.

=item Responsabilidade pessoal

Se você tem um problema em seu script, é só isso: problema seu.
Você deve fazer tudo o que puder para resolver o problema por si
mesmo. Lembre-se todo mundo têm seus próprios scripts, o que
significa que todo mundo têm seus próprios problemas. Faça seu
dever de casa e dê o melhor de si antes de aborrecer outra pessoa
com os seus problemas. Se você tentar honestamente tudo neste guia
e ainda assim não consegue resolver o problema, daí sim você deu o
melhor de si e é hora de aborrecer outra pessoa.

=item Mude a maneira como você faz as coisas

Corrija as coisas para que você não tenha o mesmo problema
novamente.  O problema é provavelmente B<como> você escreve o seu
código, e não B<que> código escreve. Mude a maneira como você faz
as coisas para facilitar a sua vida. Não tente Perl adaptar-se a
você, porque não irá conseguir. Adapte-se ao Perl. É só uma
linguagem, não é um modo de vida.

=back

=head2 Meu Método

=over 4

=item O seu código compila em modo estrito?

Se você já não estiver usando o modo estrito, ligue-o. Os gurus de
Perl são gurus porque eles usam "strict", o que lhes dá mais tempo
para resolver outros problemas, aprender coisas novas, e enviar
módulos que funcionam para o CPAN.

Você pode ligar o modo estrito no código com o pragma "strict".

	use strict;

Você pode ligar o modo estrito na linha de comando com a opção "-M"
do perl.

	perl -Mstrict script.pl

Você pode achar que o modo estrito lhe chateia, mas após algumas
semanas de programação com ele ligado, você escreverá código
melhor, passará menos tempo procurando erros simples, e
provavelmente não precisará deste guia.

=item O que é o aviso?

Perl o avisará de um monte de construções questionáveis. Ligue os
avisos e ajude Perl a ajudá-lo.

Você pode utilizar a opção "-w" na linha do "she-bang".

	#!/usr/bin/perl -w

Você pode ligar os avisos na linha de comando.

	perl -w script.pl

Você pode utilizar avisos lexicamente limitados com todo tipo de
características interessantes. Veja L<warnings> para os detalhes.

	use warnings;

Se você não compreender um aviso, você pode procurar uma versão
mais prolixa do mesmo em L<perldiag> ou você pode utilizar o pragma
"diagnostics" no seu código.

	use diagnostics;

=item Resolva o primeiro problema primeiro!

Depois de receber erros ou avisos do perl, conserte a primeira
mensagem e depois veja se o perl ainda emite as outras mensagens.
Essas mensagens extras costumam ser artefatos do primeiro problema.

=item Veja o código antes da linha cujo número está na mensagem!

O perl lhe dá mensagens de aviso quando ele fica preocupado --
não antes. Quando ele fica preocupado, normalmente o problema já
ocorreu e a linha onde ele está trabalhando está, de fato,
B<depois> do problema. Dê uma olhada em algumas expressões antes da
linha cujo número aparece na mensagem de aviso ou de erro.

=item Esse valor é o que você pensa que é?

Não adivinhe! Examine de fato o valor logo antes de que você irá
usá-lo em uma expressão. O melhor depurador ("debugger") do
universo é "print".

	print STDERR "O valor é [$valor]\n";

Eu coloco $valor entre colchetes de modo a poder ver quaisquer
espaços em branco ou mudanças de linha no início ou no final.

Se o valor é outra coisa que não um escalar, eu uso Data::Dumper
para imprimir as estruturas de dados.

	require Data::Dumper;

	print STDERR "O hash é ", Data::Dumper::Dumper( \%hash ), "\n";

Se o valor não for aquilo que você pensa que é, volte alguns passos
e tente novamente! Faça isso até você encontrar o ponto no qual o
valor para de ser aquilo que você acha que deveria ser!

Você também pode utilizar o depurador que perl tem embutido com sua
opção "-d". Veja L<perldebug> para detalhes.

	perl -d script.pl

Você pode, também, usar outros depuradores ou ambientes de
desenvolvimento, como ptkdb (um "debugger" gráfico baseado em Tk)
ou Komodo (IDE para perl da ActiveState baseado no Mozilla).

=item Você está usando a função corretamente?

Eu tenho programado em Perl por um longo tempo e ainda olho em
L<perlfunc> quase todo dia. Algumas coisas eu simplesmente não
consigo manter certas, e às vezes eu estou tão privado de sono que
perco todos os meus sentidos e fico me perguntando porque sprintf()
não está imprimindo na tela.

Você pode procurar por uma função em particular com o comando
perldoc e sua opção "-f".

	perldoc -f nome_funcao

Se você está utilizando um módulo, confira a documentação para ter
certeza de que você o está usando da maneira correta. Você pode
checar a documentação do módulo usando perldoc.

	perldoc Nome::Modulo

=item Você está utilizado a variável especial correta?

Novamente, eu constantemente consulto L<perlvar>. Bem, não
realmente, porque eu acho que L<The Perl Pocket Reference> (A
Referência de Bolso de Perl) é bem mais fácil de usar.

=item Você tem a versão correta do módulo?

Alguns módulos mudam de comportamento entre versões. Você tem a
versão do módulo que pensa ter? Você pode conferir a versão da
maioria dos módulos com o seguinte comando de uma única linha
("one-liner"):

	perl -MNome::Modulo -le 'print Nome::Modulo->VERSION';

Se você ler a maior parte da documentação no seu computador local,
em http://www.perldoc.com/, ou http://search.cpan.org/, certamente
irá encontrar diferenças nas versões da documentação.

=item Você constuiu um pequeno caso de teste?

Se você está tentando algo novo, ou pensa que um pedaço em
particular de código está agindo de maneira estranha, escreva o
mais sucinto programa de teste que use somente esse pedaço. Isso
remove a maioria dos outros fatores de sua consideração. Se o
pequeno programa de teste faz o que você acha que deveria fazer, o
problema provavelmente não é naquele código. Se o programa de teste
não faz o que você acha que deveria, então talvez você tenha
encontrado a origem do seu problema.

=item Você checou o ambiente?

Algumas coisas dependem de variáveis de ambiente. Tem certeza que
elas estão com os valores corretos? O seu ambiente é o mesmo que o
programa irá ver quando for executado? Lembre-se que programas que
irão executar no ambiente CGI ou como "cron jobs" podem ver
ambientes diferentes do que você tem na sua "shell" interativa,
expecialmente se estiverem em computadores diferentes.

Perl armazena as variáveis de ambiente em %ENV. Se você precisa de
uma ou mais dessas variáveis, esteja pronto para suprir um valor
"default" se ela não existir, mesmo que isso seja somente para os
testes.

Se você ainda tiver problemas, inspecione o ambiente.

	require Data::Dumper;
	print STDERR Data::Dumper::Dumper( \%ENV );

=item Procurou no Google?

Se você tem um problema, é possível que alguém mais já tenha tido o
mesmo problema. Veja se alguma dessas pessoas postou alguma coisa
no grupo usenet comp.lang.misc.perl procurando no Google Groups
(http://groups.google.com/). A diferença entre as pessoas que fazem
perguntas na usenet e aquelas que respondem é a habilidade de usar
o Google Groups efetivamente.

=item Você utilizou o "profiler" na aplicação?

Se você quer encontrar as partes lentas do programa, já utilizou um
"profiler" nele? Deixe que Devel::SmallProf faça o trabalho pesado
por você. Ele conta as vezes que perl executa uma linha de código,
bem como quanto tempo ele leva, e gera um belo relatório.

=item Qual teste falha?

Se você tem uma "suite" de testes, qual teste falha? Você deve
poder encontrar o erro muito rapidamente, visto que cada teste deve
exercitar somente um pequeno pedaço de código.

Se você não fez uma "suite" de testes, porque não fazê-la? Se você
tem um script realmente pequeno, ou se esse for um script que você
somente utilizará uma vez ("one-off"), então eu não lhe obrigarei a
escrever alguns testes. Entretanto, qualquer coisa maior que isso
realmente se beneficia de alguns scripts de teste. Test::Harness
faz com que isso seja tão simples que você não tem realmente
nenhuma desculpa para não fazê-lo. Se você não tem tempo, talvez
você esteja gastando tempo demais depurando scripts sem testes.
MakeMaker não é só para módulos.

=item Já falou com seu ursinho?

Explique seu problema em voz alta. Diga as palavras.

Por alguns anos eu tive o prazer de trabalhar com um programador
realmente muito bom, que conseguia resolver quase tudo. Quando eu
ficava emperrado eu ia até a sua escrivaninha, e começava a
explicar o meu problema. Normalmente, eu não chegava à quarta frase
sem dizer "Deixa pra lá -- já entendi". Ele também nunca errava.

Como você provavelmente necessitará tanto disso, recomendo algum
tipo de brinquedo de pelúcia que possa fazer o papel de seu
terapeuta Perl de maneira que você não aborreça seus colegas. Eu
tenho um ursinho que fica na minha escrivaninha e explico os
problemas a ele. Minha namorada nem presta mais atenção quando eu
falo sozinho.

=item O problema parece diferente no papel?

Você tem estado olhando fixamente para a tela do computador, então,
talvez um meio diferente lhe fará olhar as coisas de uma maneira
diferente. Tente olhar para uma impressão do seu programa.

=item Já assistiu o "Daily Show com Jon Stewart" ou "Os Simpsons"?

Sério. Talvez você não goste do Jon Stewart ou do Homer Simpson,
então escolha outra coisa. Dê um tempo. Pare de pensar no problema
um pouco e deixe sua mente relaxar. Volte ao problema depois e o
conserto pode aparecer imediatamente.

=item Já empacotou seu ego?

Se você ainda não conseguiu até agora, o problema pode ser
psicológico. Você pode estar emocionalmente ligado a uma certa
parte do código, e então não alterá-la. Você pode também pensar que
todo mundo está errado, menos você. Quando você o faz, deixa de
considerar seriamente a mais provável fonte dos "bugs": você mesmo.
Não ignore nada. Verifique tudo.

=head1 AUTOR

brian d foy, E<lt>bdfoy@cpan.orgE<gt>

Tradução ao português (brasileiro) de Humberto Massa
E<lt>massa@cpan.org<gt>, supostamente com permissão do autor :-)

Original: http://www252.pair.com/comdog/brian%27s_guide.pod

=head2 Notas do tradutor

=item Correções

Esta tradução somente foi corrigida por mim. Talvez ela se beneficie
de mais alguns pares de olhos para ficar perfeita.

=item Data::Dumper

Dependendo da profundidade da estrutura que eu tenho que verificar,
eu às vezes prefiro usar o módulo YAML para me dar uma
representação que eu acho mais "visível". A utilização é semelhante
à do Data::Dumper:

	require YAML;

	print STDERR YAML::Dump( \%hash );

=item IDEs

Eu tenho experimentado o Eclipse para trabalhar com Perl, mas ainda
não cheguei a nenhuma conclusão se gosto ou não.

=item Português e Unicode

Para desenvolver bem em Perl, brasilianos e portugueses devem
memorizar todas as características da linguagem em relação ao
Unicode. Mas, em particular, eu utilizo em quase todos os meus
módulos o seguinte código:

        use utf8;
        use open qw(:std :locale);
        use locale;

A primeira linha indica ao perl que o arquivo fonte está codificado
em UTF-8. Caso a sua codificação nativa seja outra, você pode usar

        use encoding 'latin1';

ou

        use encoding 'cp1252';

conforme seja o caso. Nunca, nunca use "use encoding ':locale'"...
como o locale varia de computador para computador, você estaria
informando ao Perl que a codificação do arquivo fonte é a mesma do
computador onde ele está e, se ele foi criado em outro computador,
isso pode não ser verdade.

A segunda linha indica ao perl que você quer que ele abra todos os
arquivos (inclusive STDIN, STDOUT e STDERR) no modo Unicode,
decodificando as entradas da codficação do locale corrente, e
codificando as saídas nessa mesma codificação.

A terceira linha afeta coisas como datas e ordenação de strings com
acentos, sempre seguindo os padrões do computador onde o código vai
rodar.

Eu descobri que essas três linhas salvam minha vida várias vezes
quando eu tenho que pensar em problemas de codificação Unicode
(especialmente num ambiente híbrido unix/windows, onde algumas
máquinas estão na codificação latin1, as máquinas windows em
utf16le ou cp1252, e outras em utf-8).

=head1 DIREITOS AUTORAIS

Copyright 2002, Perl Documentation Project,
All Rights Reserved

=cut