Estilo de Codificação do Kernel do Linux (Linux Kernel Coding Style)

Este é um pequeno documento descrevendo o estilo de codificação ideal para o kernel do Linux. O estilo de codificação é muito pessoal, e eu não irei forçar meu estilo para ninguém, mas este é o modo para qualquer coisa que eu tenha que manter, e eu preferiria por vários outros motivos também. Por favor pelo menos considere os pontos expostos aqui.

Primeiramente, eu sugiro imprimir uma cópia dos padrões de codificação do GNU e NÃO os ler. Queime-os, é um grande ato simbólico.

De qualquer maneira, aqui vai:

Capítulo 1: Indentação

Tabulações são 8 caracteres, e portanto as indentações também são de 8 caracteres. Há movimentos hereges que tentam fazer a indentação com 4 (ou mesmo 2!) caracteres, e isto é quase o mesmo que tentar definir o valor de PI para ser 3.

Razão: a idéia por trás da indentação é definir claramente aonde um bloco de controle começa e termina. Especialmente quando você está olhando para a sua tela por 20 horas seguidas, você irá achar muito mais fácil ver como a indentação funciona se você usa indentações largas.

Agora, algumas pessoas irão dizer que ter uma indentação de 8 caracteres faz com que o código se mova muito longe para a direita, e torna difícil a leitura em um terminal com 80 colunas. A resposta para isso é que se você precisa mais que 3 níveis de indentação, você está enrolado, e deve consertar o seu programa.

Resumindo, indentações com 8 caracteres fazem as coisas mais fáceis de serem lidas, e têm o benefício de avisar a você quando está aninhando muito as suas funções. Preste atenção neste aviso.

Capítulo 2: Colocando chaves

A outra questão que sempre surge na programação em C é a colocação de chaves. Ao contrário do tamanho da indentação, há poucas razões técnicas para a escolha de uma estratégia de colocação sobre outra, mas a maneira preferida, como mostrado para nós pelos profetas Kernighan e Ritchie, e colocar a chave que abre por último na linha, e colocar a chave que fecha primeiro, deste modo:

        if (x eh verdadeiro) {
                faz y
        }

Entretanto, há um caso especial, chamado funções: elas têm a chave que abre no começo da próxima linha, assim:

        int funcao(int x)
        {
                corpo da funcao
        }

Pessoas heréticas em todo o mundo têm reclamado que esta inconsistência é... bem... inconsistente, mas todas as pessoas que pensam corretamente sabem que (a) K&R estão certos e (b) K&R estão certos. Além disso, as funções são especiais de qualquer modo (você não pode aninhá-las em C).

Note que a chave que fecha é o único componente da sua linha, exceto nos casos onde é seguido por uma continuação da mesma declaração, ou seja, um "while" em uma declaração "do" ou um "else" em uma declaração "if", como esta:

        do {
                corpo do laco do
        } while (condicao);

e

        if (x == y) {
                ..
        } else if (x > y) {
                ...
        } else {
                ....
        }

Razão: K&R.

Note que esta colocação das chaves também minimiza o número de linhas vazias (ou quase vazias), sem perda de entendimento. Assim, como a quantidade de linhas em sua tela não é um recurso renovável (pense em terminais com 25 linhas), você tem mais linhas vazias para colocar os comentários.

Capítulo 3: Nomenclatura

C é uma linguagem Espartana, e também deve ser a sua nomenclatura. Ao contrário de programadores de Modula-2 e Pascal, programadores de C não usam nomes bonitos como EstaVariavelEUmContadorTemporario. Um programador de C chamaria esta variável de "tmp", que ‚ muito mais fácil de escrever, e nem por isso mais difícil de entender.

ENTRETANTO, enquanto o uso de nomes com caixa-alta e caixa-baixa é duvidoso, nomes descritivos para variáveis globais é necessário. Chamar uma variável global de "foo" é uma ofensa.

Variáveis GLOBAIS (para serem usadas somente se você realmente precisar delas) precisam ter nomes descritivos, assim como funções globais. Se você tem uma função que conta o número de usuários ativos, você deve chama-la de "conta_usuarios_ativos()" ou similar, você não deve chama-la de "cntusr()".

Codificar o tipo de uma função no seu nome (chamado de Notação Húngara) é prejudicial ao cérebro - de qualquer maneira o compilador sabe os tipos e pode verificá-los, e isto somente confunde o programador. Não é de se admirar por que a Microsoft faz programas com erros.

Os nomes de variáveis LOCAIS devem ser curtos, e diretos ao assunto. Se você tem algum contador inteiro aleatório de laço, deve ser provavelmente chamado de "i". Chama-lo de "contador_laco" não é produtivo, e ainda existe alguma chance de ser mal interpretado. Similarmente, "tmp" pode ser qualquer tipo de variável que é usado para conter um valor temporário.

Se você está com medo de misturar os nomes de suas variáveis locais, você tem um outro problema, que é chamado de síndrome do descontrole do hormônio de crescimento de função. Veja o próximo capítulo.

Capítulo 4: Funções

As funções devem ser pequenas e práticas, e fazer somente uma coisa. Elas devem preencher uma ou duas telas completas de texto (o tamanho de tela ISO/ANSI é 80x24, como todos nós sabemos), e fazer somente uma coisa e fazer isto bem.

O tamanho máximo de uma função é inversamente proporcional à complexidade e ao nível de indentação desta função. Então, se você tem uma simples função que é somente uma comprida (mas simples) cláusula case, onde você tem que fazer várias coisas pequenas para muitos diferentes cases, está correto ter uma função longa.

Entretanto, se você tem uma função complexa e suspeita que um aluno da escola primária não muito brilhante pode nem mesmo entender do que a função se trata, você deve aderir aos limites máximos mais atenciosamente. Use funções de ajuda com nomes descritivos (você pode pedir ao compilador para colocá-las em inline se a performe é um ponto crítico, e ele provavelmente irá fazer um melhor trabalho do que você teria feito).

Outra avaliação da função é o número de variáveis locais. Elas não devem exceder 5 a 10, ou você está fazendo alguma coisa errada. Repense a função, e divida-a em pedaços menores. Um cérebro humano geralmente pode manter atenção em aproximadamente 7 coisas diferentes, qualquer coisa a mais ele fica confuso. Você sabe que você é brilhante, mas talvez gostaria de entender o que você fez há 2 semanas atrás agora.

Capítulo 5: Comentários

Comentários são bons, mas há também o perigo de super-documentar. NUNCA tente explicar COMO o seu código funciona em um comentário: é muito melhor escrever o código para que o modo como funciona seja óbvio, e é uma perda de tempo tentar explicar um código mal escrito.

Geralmente, você quer que os seus comentários digam o QUE o seu código faz, não COMO. Tente evitar colocar comentários dentro do corpo de uma função: se a função é tão complexa que você precise comentar partes separadas da mesma, deveria voltar ao capítulo 4. Você pode fazer pequenos comentários para notificar ou avisar sobre algo particularmente interessante (ou feio), mas tente evitar excessos. Ao contrário, ponha os comentários no cabeçalho da função, avisando às pessoas o que ela faz, e possivelmente POR QUE ela faz isso.

Capítulo 6: Você fez uma bagunça

Tudo bem, todos nós fazemos. Você provavelmente foi avisado pelo seu ajudante usuário de linux por muito tempo que o "GNU emacs" formata o código fonte C automaticamente para você, e você notou que sim, ele faz isso, mas os defaults que ele usa são menos que desejáveis (de fato, eles são piores que uma digitação aleatória - um número infinito de macacos digitando no GNU emacs nunca iriam fazer um bom programa). Então, você tanto pode se livrar do GNU emacs como mudá-lo para que use valores mais sanos. Para fazer o último, você pode adicionar o seguinte no seu arquivo .emacs:

(defun linux-c-mode ()
  "Modo C com defaults ajustados para uso com o kernel do Linux."
  (interactive)
  (c-mode)
  (setq c-indent-level 8)
  (setq c-brace-imaginary-offset 0)
  (setq c-brace-offset -8)
  (setq c-argdecl-indent 8)
  (setq c-label-offset -8)
  (setq c-continued-statement-offset 8)
  (setq indent-tabs-mode nil)
  (setq tab-width 8))

Isto irá definir o comando M-x linux-c-mode. Quando hackear um módulo, se você colocar a string -*- linux-c -*- em algum lugar nas primeiras duas linhas, este modo será automaticamente ativado. Você também pode querer adicionar

(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode)
                       auto-mode-alist))

no seu arquivo .emacs se você quiser ter linux-c-mode ativado automagicamente quando você editar arquivos fonte dentro do /usr/src/linux.

Mas mesmo que você falhe em fazer o emacs fazer uma formatação lógica, nem tudo está perdido: use "indent".

Agora, novamente, o GNU indent tem as mesmas configurações confusas que o GNU emacs, e é por isso que você tem que dar a ele algumas opções de linha de comando. Entretanto, isto não é tão ruim assim, porque mesmo os autores do GNU indent reconheceram a autoridade do K&R (as pessoas do GNU não são más, estão somente severamente desencaminhadas neste sentido), então você somente tem que dar ao indent as opções "-kr -i8" (significa "K&R, 8 carracteres de indentação").

"indent" tem várias opções, e especialmente quando se trata de reformatação você deve dar uma olhada na página do manual. Mas lembre-se: "indent" não é uma solução para uma má programação.

Copyright 1996 Linus Torvalds
Cópia e redistribuição permitida sem royalty contanto que esta notificação esteja preservada.
Traduzido por Erik Kohler. <ekohler at programmer.net>

Retorna