Development/Tutorials/Code Checking (pt BR): Difference between revisions

    From KDE TechBase
    No edit summary
    Line 156: Line 156:
    ====Module=spelling====
    ====Module=spelling====


    '''Risk from Fixing:''' Baixo
    '''Índice de risco:''' Baixo


    Erros de ortografia nos comentários e nas cadeias devem ser corrigidos, pois podem aparecer mais tarde na documentação da API, manuais, etc strings mal escritas tornam o trabalho do tradutor mais difícil. Por favor, utilize Inglês dos EUA.
    Erros de ortografia nos comentários e nas cadeias devem ser corrigidos, pois podem aparecer mais tarde na documentação da API, manuais, etc strings mal escritas tornam o trabalho do tradutor mais difícil. Por favor, utilize Inglês dos EUA.
    Line 173: Line 173:
    ====Module=doublequote_chars====
    ====Module=doublequote_chars====


    '''Risk from Fixing:''' Baixo
    '''Índice de risco:''' Baixo


    Adicionar caracteres a uma QString é mais rápido se os caracteres são
    Adicionar caracteres a uma QString é mais rápido se os caracteres são
    Line 205: Line 205:
    ====Module=nullstrassign====
    ====Module=nullstrassign====


    '''Risk from Fixing:''' Low
    '''Índice de risco:''' Low


    Não atribua QString::null or QString() to a QString. Ao invés disso use o método .clear().
    Não atribua QString::null or QString() to a QString. Ao invés disso use o método .clear().
    Line 259: Line 259:
    '''Mensagem:''' values or keys iteration
    '''Mensagem:''' values or keys iteration


    '''Risk from Fixing:''' Medium to High
    '''Índice de risco:''' Medium to High


    http://tsdgeos.blogspot.com/2009/04/how-to-make-foreach-loops-that-dont.html
    http://tsdgeos.blogspot.com/2009/04/how-to-make-foreach-loops-that-dont.html
    Line 276: Line 276:
    ====Module=strings====
    ====Module=strings====


    '''Message:''' QLatin1String issues
    '''Mensagem:''' QLatin1String issues


    '''Risk from Fixing:''' Low to Medium
    '''Índice de risco:''' Low to Medium
     
    Some QString methods (like startsWith() and endsWith()) are more efficient if they are passed a QLatin1String, avoiding an implicit conversion from const char *.


    Alguns métodos QString (como startsWith() e endsWith())são mais eficientes se são passados com QLatin1String, evitando uma conversão implicita de const char *.
    Alguns métodos QString (como startsWith() e endsWith())são mais eficientes se são passados com QLatin1String, evitando uma conversão implicita de const char *.
    Line 312: Line 310:
    '''Mensagem:''' includes duplicados
    '''Mensagem:''' includes duplicados


    '''Risk from Fixing:''' Baixo
    '''Índice de risco:''' Baixo


    O mesmo arquivo foi incluído duas vezes, remova a segunda ocorrência.
    O mesmo arquivo foi incluído duas vezes, remova a segunda ocorrência.
    Line 320: Line 318:
    '''Mensagem:''' inclua seu próprio _p header primeiro  
    '''Mensagem:''' inclua seu próprio _p header primeiro  


    '''Risk from Fixing:''' Médio
    '''Índice de risco:''' Médio


    O arquivo cpp deve incluir as suas próprias .h e os headers _p.h primeiro no arquivo (abaixo do config.h). Mova o include para a posição correta. Você pode precisar ajustar os includes e forward declarations em outros arquivos, como um resultado, o compilador irá informar sobre isso.
    O arquivo cpp deve incluir as suas próprias .h e os headers _p.h primeiro no arquivo (abaixo do config.h). Mova o include para a posição correta. Você pode precisar ajustar os includes e forward declarations em outros arquivos, como um resultado, o compilador irá informar sobre isso.
    Line 326: Line 324:
    '''Mensagem:''' faltando ou include guard imprório no header
    '''Mensagem:''' faltando ou include guard imprório no header


    '''Risk from Fixing:''' Baixo
    '''Índice de risco:''' Baixo


    Os include guards estão faltando, ou eles não estão com as macro names apropriadamente codificadas, por exemplo, não inclui o class name.
    Os include guards estão faltando, ou eles não estão com as macro names apropriadamente codificadas, por exemplo, não inclui o class name.
    Line 351: Line 349:
    ====Module=qclasses====
    ====Module=qclasses====


    '''Risk from Fixing:''' Médio
    '''Índice de risco:''' Médio


    Classes do Qt depreciadas e classes que têm uma versão do KDE não devem ser utilizado. Também as versões do KDE de alguns elementos GUI do Qt fornecem uma aparência consistente para o desktop KDE. Veja http://techbase.kde.org/Policies/API_to_Avoid
    Classes do Qt depreciadas e classes que têm uma versão do KDE não devem ser utilizado. Também as versões do KDE de alguns elementos GUI do Qt fornecem uma aparência consistente para o desktop KDE. Veja http://techbase.kde.org/Policies/API_to_Avoid

    Revision as of 12:46, 29 January 2011


    Development/Tutorials/Code Checking


    Code Checking

    Há muitas maneiras de encontrar bugs no código do KDE. Cada vez mais, os desenvolvedores do KDE estão usando ferramentas automatizadas. Você pode usar algumas dessas ferramentas para melhorar o seu próprio código.

    O KDE 'Krazy' Checker

    Desenvolvedores do KDE tem um simples conjunto de testes que são conhecidos coletivamente como "Krazy". Esses testes foram desenvolvidos originalmente para ser executado como parte de um conjunto de testes em uma máquina conhecida como http://www.englishbreakfastnetwork.org, ou EBN. Você pode ver os resultados da execução de diversos testes noEBN (em http://www.englishbreakfastnetwork.org/krazy/).

    Você também pode executar os testes de si mesmo. Para fazer isso, você precisa obter uma cópia do código krazy2/install.txt e instalá-los. Você pode testar um único arquivo (usando o aplicativo krazy2) ou uma árvore inteira, incluindo subdiretórios (usando o aplicativo krazy2all).

    Como funciona o Krazy

    Os testes Krazy são essencialmente uma forma de análise estática - verifica o código-fonte, mas não como ele é executado.

    Krazy existe como um framework formado por diferentes testes, e um conjunto de plugins. Os testes são chamados de krazy2, krazy2all e krazy2ebn. Os testes apenas chamam um ou mais plugins no código apropriado, e formatam os resultados para mostrar.

    Nesta fase, a maioria dos testes são escritos em perl, porém um escrito em C + + (usando Qt) e é bem possível adicionar seus próprios testes, ou para modificar um teste - todas o código fonte é fornecido.

    Instalando o Krazy

    Krazy precisa ser instalado antes de usar. Krazy tem duas formas diferentes de ser instalado - você pode modificar o script krazy2/install.sh e executá-lo, ou siga as instruções no arquivo krazy2/install.txt. Eu recomendo a segunda opção.

    Você pode precisar instalar módulos adicionais do perl como XML::LibXML, veja como:

    linux-pudb:~/krazy2 # ./install.sh 
    MakeMaker FATAL: prerequisites not found.
        Tie::IxHash not installed
        XML::LibXML not installed
    
     Por favor instale esses primeiros módulos e execute novamente 'perl Makefile.PL'.
    linux-pudb:~/krazy2 # perl -mCPAN -e CPAN::shell
    

    Você talvez tenha que responder 25 questões sem utilidade aqui. Neste caso, pressione ENTER 25 vezes. Então você chega aqui:

    cpan[1]> install XML::LibXML
    

    O Tie::IxHash eu instalei a partir do repositório da distro (libtie-ixhash-perl) e também o pacote perl-doc é necessário para instalar.

    Note
    Eu tive um pequeno problema com o plugin que é construída a partir do C + +, porque instalei o plugin no diretório errado. Se estiver faltando o passbyvalue plugin, então talvez seja necessário para movê-lo para o diretório que contém o resto de seus plugins.


    Usando o Krazy

    Krazy vem com uma página principal muito boa, que lhe dá várias opções e um exemplo de uso. O arquivo é gerado na instalação. Esta é definitivamente uma leitura recomendada!

    Como mencionado acima, existem três testes - krazy2, krazy2ebn and krazy2all. Se você está tentando verificar um único arquivo, então krazy2 é a ferramenta certa. Se você está tentando verificar uma árvore (por exemplo, uma aplicação ou todo um módulo versionado), então krazy2all é mais útil. krazy2all não tem uma página, mas você pode obter uma lista das opções com krazy2all --help. Você também pode usar krazy2 para obter informações sobre os vários plugins que podem ajudar você a entender mais sobre krazy2all.

    krazy2ebn é a ferramenta que roda sobre o código base do KDE, a EBN e não deve ser executado localmente. No entanto, por favor consulte [[# Controlando Krazy na EBN | Controle Krazy sobre] EBN] abaixo para saber como você pode controlar quais plugins são executados, e que os arquivos são processados pelo programa krazy2ebn na máquina EBN.

    Lembre-se que Krazy não altera o seu código - apenas examina. Assim, você pode experimentar de modo seguro executando verificações do Krazy até ter certeza de que você entenda o que está acontecendo.

    Da mesma forma, o que significa que Krazy não resolve os problemas - só tenta reportá-los. Entendendo o que está sendo reportado, e como corrigir, é com você. Você também deve lembrar que a política de commit do KDE é de não dar commit em código que você não entende. Assim, corrigir de um erro de ortografia em um comentário é bastante seguro, mas alterar cegamente o código para parar os avisos do Krazy não é uma boa idéia.


    Diretivas In-Code

    Os plugins do Krazy suportam a seguinte lista de diretivas in-code:

    • //krazy:skip - nenhum teste será executado nesse arquivo.
    • //krazy:excludeall=<name1[,name2,...,nameN]> - os testes do Krazy name1, etc não serão executados nesses arquivos. Múltiplas ocorrência de krazy:excludeall são permitidas.
    • //krazy:exclude=<name1[,name2,...,nameN]> - os testes name1, etc. não serão executados na linha onde essa diretiva for encontrada (veja a next section abaixo para mais informações).

    Note que essas diretivas devem ser no estilo dos comentários em C++ que podem ser colocados em qualquer lugar no arquivo (exceto embutido em comentários em C)

    Omitindo false-positives

    Os testes Krazy são projetados para minimizar os false-positives (isto é, os alertas que não representam problemas reais). No entanto, porque a maioria dos testes são realizados em uma única linha, existem alguns testes que podem produzir um false-positive. Por exemplo, o código que faz algo como:

    QString mystring; mystring += "/";

    Será sinalizado pelo verificador doublequote_chars, porque é mais eficiente para adicionar um caracter simples, como mostrado abaixo:

    QString mystring; // note that we are using single quotes // this is a char, not a char array mystring += '/';

    Esse mesmo verificador irá produzir um falso positivo para o código seguinte: std::string mystring; mystring += "/";

    Você pode suprimir esses falsos positivos, usando um formato de comentário especial. Para excluir um plugin específico de ser executado em uma linha de código, basta adicionar um comentário em C++ que contenha a string "krazy:exclude=<plugin_name>". Os plugins disponíveis atualmente podem ser encontrados no repository.

    Especificamente, para este plugin use "krazy:exclude=doublequote_chars". Por exemplo:

      lenstr = "0" + lenstr;
    

    becomes

      lenstr = "0" + lenstr;  // krazy:exclude=doublequote_chars
    

    Note
    Usando o estilo C (/* */) comentários não vão funcionar. Você deve usar o estilo C++ (//) de comentários quando notar testes sendo ignorados.


    Controlando Krazy no EBN

    Essa seção descreve como usar os arquivos .krazy para controlar a execução do Krazy no EBN. Os arquivos .krazy são usados para dizer ao Krazy ignorar específicos sub-diretórios ou arquivos, ou desativar certos plugins dentro desses módulos e sub-diretórios.

    Para ignorar um sub-diretório dentro de um módulo, por exemplo kdepim/kmail, use o diretório IGNORESUBS dentro do arquivo kdepim/.krazy, assim:

    IGNORESUBS kmail

    Ou você pode ignorar um conjunto de diretórios especificando uma lista separada por vírgulas:

    IGNORESUBS kmail,kontact,knode

    Para ignorar arquivos ou diretórios dentro de um módulo/subdir, especifique uma expressão regular que coincida com os arquivos para passar juntamente com a directiva SKIP. Por exemplo, para ignorar os diretórioskdepimlibs/kcal/libical, kdepimlibs/kcal/versit, e o arquivo kdepimlibs/kcal/fred.c, use a diretiva dentro do arquivo kdepim/kcal/.krazy:

    SKIP /libical/\|/versit/\|fred\.c

    Use a diretiva EXCLUDE para desativar uma lista de plugins para todos os arquivos dentro de um módulo/subdir:

    EXCLUDE doublequote_chars,qclasses

    Para substituir a diretiva EXCLUDE coloque um arquivo .krazy na hierarquia de diretórios, use o comando CHECK. Por exemplo, o nível do componente do arquivo .krazy deve EXCLUDE os plugins copyright e license, mas os plugins podem ser reativado em um módulo/subdir com a diretiva CHECK assim:

    CHECK copyright,license

    Note
    Módulos individuais podem ser ignorados também, mas esta é uma função administradora do EBN controlada pelos arquivos .krazy na hierarquia /usr/local/src. Veja o English Breakfast Network wiki para detalhes.


    Módulos do Krazy

    Índice de risco:

    Low: Pode ser resolvido por qualquer pessoa com um risco mínimo de erro.

    Medium: pode ser corrigido por alguém com um conhecimento adequado dos recursos C++ envolvidos, alguns testes recomendados.

    High: Deveria ser corrigido somente pelo mantenedor/proprietário do código.

    Se você não entende o código, ou você não entende a correção, então não corrija o código.

    Corrigindo apidox e erros de ortografia apenas requer uma compilação antes de enviar. Todas as outras correções devem ser testados em um nível adequado, os testes unitários são úteis para isso.

    Module=spelling

    Índice de risco: Baixo

    Erros de ortografia nos comentários e nas cadeias devem ser corrigidos, pois podem aparecer mais tarde na documentação da API, manuais, etc strings mal escritas tornam o trabalho do tradutor mais difícil. Por favor, utilize Inglês dos EUA.

    Para excluir todos os checks nos comentários no início do arquivo: // krazy:excludeall=spelling

    Para excluir todos os checks nos comentários no final da linha: // krazy:exclude=spelling

    Module=doublequote_chars

    Índice de risco: Baixo

    Adicionar caracteres a uma QString é mais rápido se os caracteres são QChars e não QStrings, ou seja, use aspas simples em vez de aspas dupla em torno de um único caracter.


    O mesmo vale para os argumentos para QString::startsWith(), QString::endsWith(), QString::remove(), QString::section(), and QString::split().

    Use QString::remove() ao invés de QString::replace(foo,"")

    Substitua QString path = oldpath + "/" + base; por QString path = oldpath + '/' + base;

    Para excluir todos os checks nos comentários no início do arquivo: // krazy:excludeall=doublequote_chars

    Para excluir todos os checks nos comentários no final da linha: // krazy:exclude=doublequote_chars

    Module=nullstrassign

    Índice de risco: Low

    Não atribua QString::null or QString() to a QString. Ao invés disso use o método .clear().

    Substitua fileName = QString::null; por fileName = QString(); com fileName.clear();

    Quando retornar uma string vazia de um método use "return QString()" quando passar uma string vazia use "QString()".


    Para excluir todos os checks nos comentários no início do arquivo: // krazy:excludeall=nullstrassign

    Para excluir todos os checks nos comentários no final da linha: // krazy:exclude=nullstrassign

    Module=foreach

    Mensagem: non-const ref iterator

    Risk from Fixing: Baixo a Médio

    Quando não estiver usando tipos POD (int, double, pointer, ...) você deve usar const & para sua foreach variáveis. Há duas razões para isso: 1) Impede que você cometa o erro de escrever loops foreach que modificam a lista, que é 'foreach(Foo f, list) f.a = f.b = f.c = 0;' compila mas não modifica o conteúdo de lista 2) Salva uma cópia da chamada do construtor para cada um dos elementos da lista

    Tenha cuidado ao lidar com ponteiros? Falso positivo para bool, qlonglong e qulonglong?

    http://tsdgeos.blogspot.com/2008/04/qforeach-is-your-friend.html

    Substitua foreach(QString str, stringList) { por foreach(const QString &str, stringList) {

    Mensagem: values or keys iteration

    Índice de risco: Medium to High

    http://tsdgeos.blogspot.com/2009/04/how-to-make-foreach-loops-that-dont.html

    Para excluir todos os checks nos comentários no início do arquivo: // krazy:excludeall=foreach

    Para excluir todos os checks nos comentários no final da linha: // krazy:exclude=foreach

    Module=strings

    Mensagem: QLatin1String issues

    Índice de risco: Low to Medium

    Alguns métodos QString (como startsWith() e endsWith())são mais eficientes se são passados com QLatin1String, evitando uma conversão implicita de const char *.

    Substitua aString.startsWith("init") por aString.startsWith(QLatin1String("init"))

    Um comum false positive é com QByteArray que não poder receber uma QLatin1String.

    Para excluir todos os checks nos comentários no início do arquivo: // krazy:excludeall=strings

    Para excluir todos os checks nos comentários no final da linha: // krazy:exclude=strings

    Module=includes

    Veja http://techbase.kde.org/Policies/Library_Code_Policy#Getting_.23includes_right.

    Mensagem: includes duplicados

    Índice de risco: Baixo

    O mesmo arquivo foi incluído duas vezes, remova a segunda ocorrência.

    Mensagem: inclua seu próprio header primeiro

    Mensagem: inclua seu próprio _p header primeiro

    Índice de risco: Médio

    O arquivo cpp deve incluir as suas próprias .h e os headers _p.h primeiro no arquivo (abaixo do config.h). Mova o include para a posição correta. Você pode precisar ajustar os includes e forward declarations em outros arquivos, como um resultado, o compilador irá informar sobre isso.

    Mensagem: faltando ou include guard imprório no header

    Índice de risco: Baixo

    Os include guards estão faltando, ou eles não estão com as macro names apropriadamente codificadas, por exemplo, não inclui o class name.

    Mensagem:

    Use <..> para incluir headers instalados.

    Message:

    Para incluir Qt headers de headers instalados.

    Para excluir todos os checks nos comentários no início do arquivo: // krazy:excludeall=includes

    Para excluir todos os checks nos comentários no final da linha: // krazy:exclude=includes

    Module=qclasses

    Índice de risco: Médio

    Classes do Qt depreciadas e classes que têm uma versão do KDE não devem ser utilizado. Também as versões do KDE de alguns elementos GUI do Qt fornecem uma aparência consistente para o desktop KDE. Veja http://techbase.kde.org/Policies/API_to_Avoid

    Algumas das classes K não só adicionam recursos para o Qt e podem até não ser baseadas no Qt. Por favor, consulte a documentação da API antes de portar para as classes K.

    Para excluir todos os checks nos comentários no início do arquivo: // krazy:excludeall=qclasses

    Para excluir todos os checks nos comentários no início do arquivo: // krazy:exclude=qclasses

    Compiler Warnings

    Além das diversas ferramentas Krazy, você também pode obter ajuda preciosa dos avisos que o compilador emite, especialmente se você habilitar os avisos adicionais (por documentação do seu compilador), e também se você testar com mais de um compilador (por exemplo, se você pode testar no Linux com o GCC e tanto o compilador Intel, ou no Linux com o GCC e também no Windows com o compilador Microsoft).