Por que o tio Bob sugere que os padrões de codificação não devam ser anotados se você pode evitá-lo?

Enquanto eu lia essa pergunta , a resposta mais votada citou o tio Bob nos padrões de codificação , mas fiquei confuso com esta dica:

3. Não as anote se puder evitá-la. Em vez disso, deixe o código ser o modo como os padrões são capturados.

Isso ricocheteou no meu cérebro, mas não consegui encontrar um lugar para ficar. Se uma nova pessoa se juntar à equipe ou os padrões de codificação mudarem, não haveria confusão de informações?

Por que não devo escrever um padrão de codificação?

Há algumas razões.

1. Ninguém lê documentação.
2. Ninguém segue a documentação, mesmo que a leia.
3. Ninguém atualiza a documentação, mesmo que a leia e a siga.
4. Escrever uma lista de práticas é muito menos eficaz do que criar uma cultura.

Os padrões de codificação não são sobre o que as pessoas devem fazer, mas sobre o que realmente fazem. Quando as pessoas se desviam dos padrões, isso deve ser percebido e alterado por meio de um processo de revisão de código e / ou ferramentas automatizadas.

Lembre-se de que o objetivo principal dos padrões de codificação é facilitar nossa vida. Eles são um atalho para o nosso cérebro, para que possamos filtrar as coisas necessárias das coisas importantes. É muito melhor criar uma cultura de revisão para aplicar isso do que formalizá-la em um documento.

Há outra interpretação. Não acredito que seja o que o tio Bob quis dizer, mas vale a pena considerar.

Não capture padrões de codificação em um documento. Capture-o no código, com um processo automatizado que verifica se os padrões estão sendo atendidos .

Não confie nas pessoas que fazem referência a um documento, mas, ao mesmo tempo, não confie nas pessoas que interpretam o código que já existe e identificam o que é convenção e o que é coincidência.

Incorpore algo como Checkstyle em sua compilação de confirmação. Isso pode impor regras básicas, como padrões de formatação e nomeação, e, em vez de gastar esforço mental ao considerar o estilo, tudo isso pode ser transferido para um processo idiota que é pelo menos garantido que é completo.

Se isso importa, defina estritamente o que você deseja e falhe se estiver errado.

As pessoas ignoram o real objetivo de um documento de normas de codificação, que é resolver disputas .

A maioria das decisões no padrão de codificação terá apenas um efeito muito menor na legibilidade e na produtividade. Especialmente se você adota o estilo 'normal' para o idioma, e os designers de idiomas estão começando a perceber que isso deve fazer parte das especificações (por exemplo, Go).

Por serem tão triviais, os argumentos podem se aquecer e continuar indefinidamente, causando danos reais à produtividade e à coesão da equipe. Ou pode obscurecer seu histórico de alterações com a reformatação sem fim entre os estilos preferidos de duas ou mais pessoas.

Ter um padrão escrito encerra o argumento. Os gerentes podem apontar para ele e desviar a insatisfação em relação ao documento. Você pode discutir com um pedaço de papel, mas isso não vai ouvi-lo.

(Veja também A Tirania da Estruturação )

Porque comentários são mentiras .

O padrão de codificação é um grande comentário sobre o que o código deve ser. O código em si é a fonte última da verdade. A verdade, neste caso, não é o comportamento do código, é o estilo em que ele é expresso. Se seus padrões ainda não estão refletidos no seu código, você tem muito trabalho pela frente.

O tio Bob vê um comentário como falha pessoal do programador, porque prova que ele não conseguiu expressar o objetivo do fragmento de código com a própria linguagem de programação. Da mesma forma, um documento de padrões é uma falha ao expressar um estilo coerente na base de código.

Os novos programadores devem passar um tempo olhando o código, sem passar dias lendo um documento de normas com vários capítulos (eu tive que fazer isso, suspiro).

Um documento de normas não é uma má idéia, mas eu estive em lojas de programação em que a manutenção dos documentos de normas era o trabalho de alguém em período integral. Por favor, se você precisar manter um documento de normas, mantenha-o em uma página. Mas se você já possui código, ninguém deveria conseguir montar o mesmo documento em menos de um dia?

Ter padrões de código é importante. Ter um documento que dita o que são não é.

Por que o tio Bob sugere que os padrões de codificação não devam ser anotados se você pode evitá-lo?

Se você está perguntando as razões por trás da opinião dele, poderá ter uma resposta apenas se ele postar uma resposta aqui ( nossa opinião é irrelevante), no entanto ...

Por que não devo escrever um padrão de codificação?

Se você está perguntando se ele está certo : deixe-me ser o único impopular (até agora) a dizer que você não tem motivos para evitá-lo.

ESCREVA PARA BAIXO . No entanto, vou tentar explicar minhas razões ...

David sugeriu em um comentário que o ponto principal da resposta de Stephen não é por que você não deve escrever documentos, mas de que forma eles são. Se as diretrizes são formalizadas em ferramentas (não apenas na revisão manual de códigos), posso concordar (quando a lei não exige outra coisa). Observe que, infelizmente, as ferramentas não podem verificar tudo (a teoria da computação não é nossa amiga) frequentemente porque estão limitadas a uma unidade ou pacote de tradução específico ou seja qual for o seu idioma favorito chamar de limite .

No entanto, as palavras do tio Bob não me fazem pensar que ele está falando sobre isso.

Posso discordar desse especialista sênior? Sim, em quase todos os pontos do post citado (veja também a segunda parte desta resposta para obter detalhes). Vamos tentar entender o porquê (supondo que você já saiba que as diretrizes de codificação não são apenas sobre pequenos problemas de formatação ).

• Em algumas circunstâncias, os padrões de codificação por escrito são exigidos por lei.
• Eu leio a documentação e tenho certeza de que não estou sozinha. Os membros da equipe podem mudar com o tempo, o conhecimento não pode estar em uma base de código de 5 a 10 anos ou na mente dos membros da equipe. As organizações devem demitir pessoas que não seguem as diretrizes internas.
• Os padrões de codificação, depois de aprovados , não mudam com frequência e se você deseja saber sobre isso. Se os padrões foram alterados, sua documentação (em código) está desatualizada porque todo o seu código não segue o novo padrão. A reformatação / refatoração pode ser lenta, mas você sempre tem uma orientação autorizada por escrito a seguir.
• É melhor ler um documento de 5 páginas do que inspecionar 10 / 20K LOC para extrapolar uma regra (que você pode entender errado, BTW), sem dúvida.
• É irônico que alguém que escreveu muitos livros sobre princípios de design e estilo de codificação esteja sugerindo que você não escreva suas próprias diretrizes, então não é melhor se ele nos der um exemplo de código? Não, porque as diretrizes escritas não apenas lhe dizem o que fazer, mas também duas outras coisas que o código não tem: o que não fazer e razões para fazê-lo ou não.

A "programação auto-organizada gratuita" é boa para um ninja de 16 anos, mas as organizações têm outros requisitos :

• A qualidade do código deve ser concedida (e definida) no nível da empresa - não é algo que uma única equipe possa decidir. Talvez eles nem tenham as habilidades necessárias para decidir o que é melhor (quantos desenvolvedores, por exemplo, possuem todas as habilidades necessárias para revisar o MISRA ou até mesmo entender apenas cada regra?)
• Os membros podem ser movidos por equipes diferentes: se todos seguirem os mesmos padrões de codificação, a integração será suave e menos propensa a erros.
• Se uma equipe é auto-organizada, os padrões evoluirão com o tempo quando os membros da equipe mudarem - você terá uma enorme base de código que não segue os padrões atualmente aceitos .

Se você está pensando nas pessoas antes do processo , só posso sugerir a leitura sobre o TPS: os seres humanos são uma parte central do Lean, mas os procedimentos são altamente formalizados.

É claro que uma organização pequena com apenas uma equipe pode deixar que a equipe decida os padrões a serem adotados, mas deve ser anotada. Aqui, no Programmers.SE, você pode ler as postagens de Eric Lippert: Suponho que todos concordamos que ele é um desenvolvedor experiente; quando trabalhou na Microsoft, ele teve que seguir suas diretrizes escritas (mesmo que algumas regras possam estar erradas , não aplicáveis ou inúteis). para ele.) E Jon Skeet? As diretrizes do Google são bastante rigorosas (e muitas pessoas não concordam com elas), mas ele deve seguir essas diretrizes. É desrespeitoso para eles? Não, eles provavelmente trabalharam para definir e melhorar essas diretrizes, uma empresa não é feita por um membro (ou uma equipe) e cada equipe não é uma ilha .

Exemplos

• Você decidiu não usar herança múltipla e classes aninhadas em C ++ porque os membros reais da equipe não a entendem bem . Mais tarde, alguém que queira usar herança múltipla deve procurar o LOC inteiro 1M para ver se ele já foi usado. É ruim porque, se as decisões de design não estão documentadas, você precisa estudar toda a base de código para entendê-las. E mesmo assim, se não foi usado, é porque é contra o padrão de codificação ou é permitido, mas simplesmente não havia situações anteriores em que a herança múltipla se encaixava bem?
• No C #, você tinha métodos sobrecarregados para fornecer parâmetros padrão, porque sua base de código foi iniciada quando parâmetros opcionais não estavam disponíveis no C #. Em seguida, você alterou e começou a usá-los (refatorando o código antigo para usá-lo toda vez que você precisava modificar essas funções). Mais tarde, você decidiu que os parâmetros opcionais são ruins e começa a evitar usá-los. Qual é a regra que seu código diz? É ruim porque o padrão evolui, mas a base de código é mais lenta e, se for sua documentação, você está com problemas.
• Jon passou da equipe A para a equipe B. Jon precisa aprender um novo padrão; enquanto estiver aprendendo, ele provavelmente introduzirá erros mais sutis (ou, se tiver sorte, levará muito tempo para entender o código existente e tornar a revisão do código mais longa).
• A equipe A passa para uma base de código pertencente à equipe B. Ele possui padrões de codificação completamente diferentes. Reescrever? Adaptar? Misturar? Todos eles são igualmente ruins.

Tio Bob

Deixe-os evoluir durante as primeiras iterações.

É verdade, até que você não tenha um padrão e sua organização tenha atribuído a você a tarefa de criar um.

Deixe que eles sejam específicos da equipe, e não da empresa.

Não, por todos os motivos explicados acima. Mesmo que você pense em formalizar apenas a formatação de código (a coisa menos útil que você pode querer formalizar) ainda tenho memória de guerras intermináveis ​​(e inúteis) sobre formatação. Não quero vivê-los repetidamente, defini-lo de uma vez por todas.

Não as anote se puder evitá-la. Em vez disso, deixe o código ser o modo como os padrões são capturados.

Não, por todos os motivos explicados acima (é claro, a menos que você refatore todo o seu código de uma só vez quando as diretrizes mudarem). Deseja deixar seu código como está? Como você inspeciona a base de código para entender as diretrizes atuais ? Procurando por idade do arquivo e adaptando seu estilo de codificação à idade do arquivo de origem?

Não legislar um bom design. (por exemplo, não diga às pessoas para não usarem o goto)

É verdade que as diretrizes devem ser curtas ou ninguém as lerá. Não repita o óbvio.

Certifique-se de que todos saibam que o padrão é sobre comunicação e nada mais.

Além disso, um bom padrão diz respeito à qualidade, a menos que você queira ter apenas um padrão sobre pequenos detalhes.

Após as primeiras iterações, reúna a equipe para decidir.

Veja o primeiro ponto e não esqueça que um padrão de codificação geralmente é um processo que levou muitos anos para ser desenvolvido e refinado: poucas iterações, talvez com desenvolvedores juniores? Realmente? Deseja confiar na memória de um membro sênior (se houver)?

Três notas:

• Na minha opinião, as desvantagens são mais graves em algumas linguagens do que em outras, por exemplo, em C ++, um padrão no nível da empresa é ainda mais necessário do que em Java.
• Esse raciocínio pode não se aplicar inteiramente (e os motivos do tio Bob podem ser menos extremos ) se você estiver trabalhando em uma empresa muito pequena, onde você tem apenas uma equipe pequena.
• Você é contratado (como equipe) e trabalhará sozinho com um novo projeto, depois o esquecerá e seguirá em frente. Nesse caso, você pode não se importar (mas seu empregador deve ...)

1. Para ser útil, um padrão de codificação não deve falar sobre questões de substância; apenas questões de estilo. Ele deve especificar apenas as coisas arbitrárias e ambíguas. por exemplo, posicionamento da chave, profundidade do recuo, espaços versus guias, convenções de nomes, etc.
2. Questões de estilo são locais, não globais. Cada equipe deve adotar seu próprio estilo peculiar, compatível com sua tarefa e sua personalidade. Isso mantém os padrões simples e leves. Os padrões corporativos ficam sobrecarregados com todas as considerações, configurações e exceções possíveis.
3. Dentro de uma equipe, o único motivo para escrever um documento separado de estilo de codificação é se o código produzido pela equipe não atender ao padrão. Nesse caso, você não tem padrão. Para ser eficaz, o padrão deve ser expresso pelo próprio código. E se for assim, não há necessidade de um documento separado.
4. Nos sistemas legados, as equipes e os estilos mudam com o tempo. Não há nada de errado nisso. O código antigo terá um estilo mais antigo. O código mais recente terá um estilo mais novo. A equipe deve estar ciente dos estilos e idades. Sempre que um novo código é escrito, ele deve estar no novo estilo, independentemente do local em que está localizado.

Por que não devo escrever um padrão de codificação?

Há muitas razões para isto. Aqui estão algumas considerações:

1. Quanto tempo as pessoas gastam "aprendendo" os padrões de código apenas para ter muito tempo para toda a equipe revisar, discutir, documentar, revisar ... etc. os padrões de código. É como discutir constantemente o seu "Manual do funcionário" - com que frequência isso faz parte da agenda de uma reunião de equipe?

2. Quando um projeto é reembolsado / arquivado / etc. então, as poucas pessoas que permanecem geralmente não podem continuar aderindo (ou talvez nem tenham lido) os padrões. A próxima coisa que você sabe, todo esse esforço para "manter o código limpo" foi praticamente desperdiçado.

3. Se o projeto for interrompido ou surgir um novo lead, é muito provável que essa pessoa ignore totalmente as regras anteriores e deseje fazê-lo de uma nova maneira. Novamente, o que foi ganho pela codificação de padrões?

Você deve ler # 6:

Após as primeiras iterações, reúna a equipe para decidir.

Em outras palavras, quando é hora de iniciar um projeto, basta seguir o fluxo por um tempo. Depois, discuta as regras gerais dos padrões de codificação que a equipe atual está usando - e basicamente siga-as. Dessa forma, você maximiza o esforço necessário para melhorar o produto e minimiza o esforço necessário para escrever, revisar e documentar o "açúcar sintático" usado na obtenção de código executável.

Muito poucas equipes obtêm enormes benefícios dos padrões de codificação. Geralmente, a "legibilidade" é muito vaga - e a maioria dos desenvolvedores não se beneficia muito com regras exatas sobre espaçamento, novas linhas, etc., mas você pode evitar desenvolvedores constantemente irritantes , tendo pelo menos algumas regras.

Outra resposta que não acho que tenha sido declarada com clareza suficiente é que isso também significa que as pessoas não seguem as regras cegamente. Isso significa que as pessoas precisam apresentar justificativas reais para suas decisões de design e convenções de codificação, em vez de depender apenas do fato de que elas foram escritas para justificá-las.

Em primeiro lugar, até onde eu sei, o tio Bob é uma pessoa Java, isso é muito importante para entender o que ele diz.

Ao trabalhar em uma equipe Java ou C #, se o código atual foi escrito por desenvolvedores experientes, é fácil para mim pegar o estilo de codificação e segui-lo. Se eu não estiver disposto a fazê-lo, talvez eu não seja a pessoa certa para o trabalho ... Se não houver revisão de código ou programação emparelhada para me buscar quando eu não seguir o estilo, a empresa terá um problema maior do que a maneira como nomeio os campos dos membros!

Java e C #, juntamente com a maioria das linguagens modernas, foram definidos para que existam poucas armadilhas "simples" para um programador se encaixar.

No entanto, quando comecei a programar, estava usando C (e depois C ++). Em C, você pode escrever código como

if (a = 3);
{
   /* spend a long time debugging this */
}

O compilador não dará um erro, e isso é difícil de detectar ao ler muito código. No entanto, se você escrever:

if (3 = a)
{
   /* looks odd, but makes sense */
}

O compilador apresenta um erro e é fácil alterar o código para 3 == a. Da mesma forma, se o padrão de codificação não permitir =ser usado dentro de uma ifcondição ou " ifdeclaração vazia ", um verificador de código poderá ser usado como parte do sistema de construção para rastrear esse erro.

Minhas visões sobre os padrões de codificação mudaram bastante quando me afastei do C / C ++: eu gostava de padrões de codificação que eram rigorosamente impostos e com muitas páginas. Agora, acho que você só precisa listar as ferramentas que estão sendo usadas e obter um acordo informal entre os membros originais da equipe em algumas convenções de nomenclatura. Não vivemos mais em um mundo de equipes de mais de 30 desenvolvedores que escrevem aplicativos em C / C ++ ...

Há uma razão pela qual nunca gostei do JScript e acho que o TypeScript é a melhor coisa que acontece no desenvolvimento da web há anos. Espero que os desenvolvedores da interface do usuário da Web ainda precisem de padrões de codificação devido aos defeitos no design de HTML / CSS / JScript etc.

Ter a fonte como padrão de codificação de auto-documentação implica duas coisas.

1. As pessoas devem consultar a base de código e revisá-la para se tornarem colaboradores proficientes. Isso é incrivelmente importante. Ler as diretrizes de codificação é uma perda de tempo em comparação com mergulhar na base de código.
2. Ele reconhece que pequenas diferenças não são importantes. É importante concordar e entender os princípios básicos. A manutenção de um estilo consistente não é seguida como l'art pour l'art. Não permite nitpickers não criativos irritar e distrair outras pessoas. Trata-se de facilitar a comunicação através do código em uma equipe.

Um documento de padrões de código atualizado e bem escrito com freqüência pode ser muito útil, mas geralmente esse não é o caso. O documento de normas não reflete os padrões de codificação atuais usados ​​pela empresa, pois é muito difícil criar um bom documento e ainda mais difícil mantê-lo atualizado.

Em vez de ter um documento de padrões de codificação ruim e enganoso, é melhor não ter nenhum e deixar que o próprio código represente esses padrões. De qualquer maneira, a parte mais importante é aplicar os padrões no código, e isso requer muito mais do que apenas um documento. Motivação, processos, treinamentos, ferramentas etc são muito mais importantes.

Uma coisa muito importante que não foi declarada com clareza suficiente é que os padrões de codificação são como a linguagem: eles evoluem. Um padrão de codificação escrito fica no caminho disso, e se não o fizer, é continuamente desatualizado e inútil.

Não ter um padrão de codificação pregado não é tão ruim assim. Se você fizer análises por pares no check-in, sempre que algo que não esteja em conformidade com o padrão de codificação entrar no repositório, isso significa que 2 pessoas pensaram nisso * e decidiram que o benefício dessa variação supera a inconsistência com o restante do código.

Não ter um padrão anotado também remove a burocracia que impediria uma equipe de uma empresa de experimentar uma nova variação do padrão de codificação para um novo projeto, seja porque eles querem experimentar alguma coisa, ou talvez porque um padrão diferente tenha aplicações práticas. em algumas das ferramentas automatizadas que eles usam.

A anotação de um padrão tende a remover mais flexibilidade do que o inicialmente previsto, além de levar bastante tempo que poderia ser gasto em outras coisas. Eu não estou dizendo que você nunca deve escrever padrões de codificação, eles certamente têm seus benefícios, especialmente se as equipes que trabalham em locais diferentes trabalham na mesma base de código.

Fortemente relacionado: Evolução dos padrões de codificação, como você lida com eles?

* Se as pessoas não pensam enquanto analisam o código no check-in, seus problemas são muito maiores do que apenas os padrões de codificação.

Mudá-los se torna um grande obstáculo, e as pessoas aderem com segurança à letra da lei, em vez de se empenharem e fazerem a coisa certa.

Chegará o dia em que parte do padrão será inútil e tornará o código pior. Algumas pessoas aderem ao padrão, porque está escrito e seguro, e porque existem regras a serem seguidas. As pessoas que desejam escrever um bom código em vez de código compatível com o padrão ficarão frustradas e irritadas. Haverá argumentos e discordâncias, enquanto que, se o padrão não fosse escrito, haveria exploração e discussão.

Eu acho que muitos posts aqui são um padrão de codificação confuso com um guia de estilo .

Garantir que os módulos desenvolvidos por equipes diferentes tenham as mesmas opções de compilador e ABI é um tipo diferente de quantos espaços são recuados.

Coisas como a maneira correta de estruturar arquivos #include e não poluir o espaço para nome global em um arquivo de cabeçalho devem ser documentadas para que possam ser usadas como uma lista de verificação durante a codificação inicial e as revisões de código.

Em particular "não use XXX porque provoca problemas de compatibilidade com YYY" não é algo que você ver por exemplo em seguir outro código, uma vez que é não existe. Portanto, deixe que o código seja o modo como os padrões são capturados pode não ser claro ou totalmente ausente para alguns tipos de padrões e, portanto, esse não pode ser um plano universal.

Algo seriamente difundido e importante, como não usar exceções ou não newem certos sistemas embarcados, não pode ser simplesmente deixado como conhecimento comum da cultura, já que "a informação é cultural (apenas)" contradiz os princípios fundamentais dos padrões de fabricação como ISO-9000, que o desenvolvedor desses sistemas embarcados está usando (por exemplo, para aplicações automotivas). Essas coisas importantes devem ser documentadas, assinadas e arquivadas de maneira formal.

Mas isso se aplica à codificação , não ao estilo .

Os inventores de C e C ++ mostram, por exemplo, o uso de nomes em minúsculas e não o CaMelCaSe. Então, por que tantos desenvolvedores não seguem o exemplo implícito da fonte? O estilo da biblioteca padrão e os materiais de ensino canônicos não devem ser o estilo implícito a seguir?

Enquanto isso, as pessoas fazem seguir o exemplo dos cabeçalhos da biblioteca padrão para coisas que não devem ser copiados, como o uso de __Uglynomes de parâmetros macro e o arquivo de inclusão não-padrão de repetição.

Portanto, ter coisas geralmente não é visto como um estilo importante ou, inversamente, ter exemplos pode não ser claro quanto ao que não deve ser seguido no código do projeto. Ambos são contra-exemplos da tese de que "estilo" (ou convenções de codificação) é melhor deixar implícito.