Policies/Kdelibs Coding Style/pt-br

Esse documento descreve o estilo de código recomendado para kdelibs. Ninguém é forçado a usá-lo, mas para ter uma formatação consistente dos seus arquivos de código-fonte é recomendado fazer uso dele.

Em síntese: o estilo de código da Kdelibs segue o estilo de código do Qt 4, com uma diferença principal: utilizar as chaves, mesmo quando o corpo de uma instrução condicional contém apenas uma linha,com uma diferença principal: utilizar as chaves, mesmo quando o corpo de uma instrução condicional contém apenas uma linha.

Indentação

• Sem abas
• 4 espaços ao invés de uma aba

Declaração de variável

• Cada declaração de variável em uma nova linha
• Cada nova palavra no nome de uma variável começa com uma letra maiúscula (o chamado camelCase)
• Evitar abreviações
• Usar nomes significativos. Não use nomes curtos, exceto:
  • Nomes de variáveis com um único caractere podem indicar contadores e variáveis temporárias cujo propósito é óbvio
  • Variáveis e funções começam com uma letra minúscula

Exemplo:

// errado
KProgressBar *prbar;
QString prtxt, errstr;

// certo
KProgressBar *downloadProgressBar;
QString progressText;
QString errorString;

Espaço em branco

• Use linhas em branco para agrupar comandos
• Use somente uma linha em branco
• Use um espaço depois de cada palavra-chave
• Para ponteiros ou referências, use um único space antes de '*' ou '&', nenhum depois
• Não use espaço após um cast

Exemplo:

// errado
QString* myString;
if(true){
}

// certo
QString *myString;
if (true) {
}

Chaves

Como uma regra básica, a abertura da chave fica na mesma linha do comando que inicia o bloco.

Exemplo:

// errado
if (true)
{
}

// certo
if (true) {
}

Exceção: A chave de abertura das implementações de função, declarações de classes, struct's e namespace's deve ser sempre colocada no início da linha seguinte.

Exemplo:

void debug(int i)
{
    qDebug("foo: %i", i);
}

class Debug
{
};

Use as chaves mesmo quando o corpo de um bloco condicional contiver apenas uma linha.

Exemplo:

// errado
if (true)
    return true;

for (int i = 0; i < 10; ++i)
    qDebug("%i", i);

// certo
if (true) {
    return true;
}

for (int i = 0; i < 10; ++i) {
    qDebug("%i", i);
}

Comando switch

Case labels ficam na mesma coluna do switch

Exemplo:

switch (myEnum) {
case Value1:
    doSomething();
    break;
case Value2:
    doSomethingElse();
    // fall through
default:
    defaultHandling();
    break;
}

Quebra de linha

Tente manter linhas menores que 100 caracteres, inserindo quebras de linha conforme for necessário.

Qt Includes

• Se você adicionar #includes para as classes do Qt, use o nome do módulo e da classe. Isso permite que a biblioteca seja utilizada sem uso excessivo de parâmetros para o compilador

Exemplo:

// errado
#include <QString>

// certo
#include <QtCore/QString>

Formatação automática com Artistic Style (astyle)

Você pode usar astyle (>=1.23) para formatar o código ou testá-lo se você tiver seguido esse documento. Execute o seguinte comando:

astyle --indent=spaces=4 --brackets=linux \
       --indent-labels --pad=oper --unpad=paren \
       --one-line=keep-statements --convert-tabs \
       --indent-preprocessor \
       `find -type f -name '*.cpp'-or -name '*.cc' -or -name '*.h'`

Com astyle (>=2.01) você precisa executar o seguinte comando:

astyle --indent=spaces=4 --brackets=linux \
       --indent-labels --pad-oper --unpad-paren --pad-header \
       --keep-one-line-statements --convert-tabs \
       --indent-preprocessor \
       `find -type f -name '*.cpp' -or -name '*.cc' -or -name '*.h'`

Você pode encontrar um shell script para executar esse comando em:

• kde-dev-scripts/astyle-kdelibs (POSIX)
• kde-dev-scripts/astyle-kdelibs.bat (Windows)

Scripts Emacs e Vim

O diretório kde-dev-scripts no módulo kdesdk contém, entre outras coisas úteis, alguns adições úteis para os editores de texto Emacs e Vim que tornam mais fácil de editar o código do KDE com eles.

Emacs

O diretório kde-emacs contém um conjunto de teclas, macros e códigos úteis em geral. Ele é compatível com o GNU Emacs e com o XEmacs.

Para iniciar o uso de kde-emacs, adicione o seguinte para seu .emacs:

(add-to-list 'load-path "/path/to/kde-emacs")
(require 'kde-emacs)

Muitas configurações podem ser alteradas pela edição do grupo "kde-emacs" via M-x customize-group.

Para mais informações, incluindo quais teclas estão mapeadas e quais configurações extras você pode adicionar ao seu .emacs, por favor, verifique kde-emacs.el

Vim

Você pode encontrar um script para o vim em kdesdk/scripts/kde-devel-vim.vim que o ajuda a manter o correto estilo de código. Além de utilizar o estilo da kdelibs por padrão, ele automaticamente utilizará o estilo do Solid e kdepim quando necessário.

Para usar o script, inclua-o em seu ~/.vimrc assim:

source /path/to/kde/sources/kdesdk/scripts/kde-devel-vim.vim

Documento criado por Urs Wolfer. Algumas partes desse documento foram adotadas do documento Qt Coding Style postado por Zack Rusin no kde-core-devel.