O que deve estar em um padrão de codificação? [fechadas]

O que deve estar em um bom padrão de codificação (leia-se: útil)?

• Coisas que o código deve ter.
• Coisas que o código não deveria ter.
• O padrão de codificação deve incluir definições das coisas que o idioma, compilador ou formatador de código impõe?
• E quanto a métricas como complexidade ciclomática, linhas por arquivo etc.?

Razões para todos os requisitos. Dessa forma, seguir o padrão não se torna algum tipo de culto à carga e as pessoas sabem que não há problema em mudar o padrão se o motivo não se aplicar mais ou violar o padrão em casos específicos em que o motivo claramente não se aplica .

Tabs vs Espaços! Recebo atualizações malucas quando um dos meus colegas acidentalmente envia várias guias para que os espaços sejam transferidos para o repositório

Convenções de nomenclatura

EDITAR: Por isso quero dizer nomear diretrizes, não nomear regras.

Por exemplo, uma diretriz seria All boolean values should begin with Is/Can/Has/etc when possible. Uma regra seriaAll boolean values must start with Is

Um padrão de codificação para um grupo deve incluir as opções do compilador para avisos e erros que devem ser abordados.

Os programadores devem estar livres para aumentar avisos para seu próprio código, mas deve haver uma linha de base para que a leitura e o trabalho com o código de outra pessoa não atrapalhem a saída que você obtém do compilador.

Esse padrão também deve abordar como os programadores podem desativar esses avisos caso a caso, caso exista um código excepcional que não esteja em conformidade.

Alguns padrões que eu gosto (eu sei que existem muitos deles, mas são esses que eu prefiro):

• 80% de cobertura de testes unitários
• Propriedade coletiva do código (escreva o código a ser lido pelos colegas de equipe, não pelo compilador)
• Escreva comentários. Escreva o que você diria para um recém-chegado.
• Mantenha simples

Os padrões de codificação ajudam um pouco quando você está escrevendo o código pela primeira vez, eles ajudam muito quando você ou seu substituto precisa atualizar o código 2 anos depois.

O padrão ideal leva ao código, onde você pode pular para qualquer página arbitrária no código e entender exatamente o que está fazendo na primeira leitura, porque

• os nomes descrevem claramente quais dados estão sendo manipulados,
• os aparelhos tornam o fluxo de controle claro,
• os comentários explicam qualquer algoritmo não óbvio etc.

Por outro lado, muitos padrões arbitrários podem atrapalhar o fluxo de escrever código. Portanto, acredito que todos os itens de uma convenção de codificação proposta devem ser avaliados com base nesses 2 critérios:

• Esta regra ajuda a garantir que o código esteja correto ?
• Esta regra ajuda a garantir que o código seja limpo ?

Se nenhum deles for verdadeiro, o item é apenas arbitrário e provavelmente desnecessário

Eu incluiria as seguintes coisas em um padrão que escrevo:

Para maior clareza:

• Organização do arquivo: especificar uma ordem fixa para os itens em um arquivo permite que a equipe navegue facilmente em outros arquivos. Você não precisa procurar para encontrar #defines ou definições de estrutura.

• Convenções de nomenclatura: Nomenclatura consistente ajuda na legibilidade. Mas evite especificar demais regras demais, que prejudicam a capacidade de gravação.

• Estrutura de código. Posicionamento de chaves, níveis de recuo, espaços x tabulações etc. Sim, isso pode ser uma forte preferência pessoal, mas o objetivo é um código claro. Encontre a melhor opção para a equipe e fique com ela.

Para correção:

• Práticas recomendadas específicas para o seu tipo de problema: Regras sobre alocação de memória, simultaneidade ou portabilidade.

• "Const Correctnesss", uso adequado de statice volatileetc.

• Regras sobre macros de pré-processador e outros recursos facilmente abusados ​​do idioma.

Idéias inspiradoras e pragmáticas que fazem as pessoas pensarem, em vez de restrições negativas que impedem as pessoas de pensar.

Caso contrário, você recebe macacos de código que têm medo de ir atrás das bananas .

O que deve estar em um padrão de codificação? O menos possível. Menos um pouco mais. E com justificativa, por favor.

Não porque eu sou um programador de cowboys que não quer processo, mas porque vi especificações pesadas de codificação sem lógica por trás - (presumivelmente) "Encontrei isso na 'Net em algum lugar de volta em 95" que acaba se tornando um pesadelo burocrático para se trabalhar.

Algumas pessoas honestamente parecem acreditar que, ao elevar os padrões, elas verão um aumento correspondente no código "qualidade" e, talvez, com essa medida. Enquanto isso, eles ignoram a arquitetura, o desempenho, o senso comum e muitas outras coisas que acabam importando mais do que o número de linhas em um arquivo.

Um procedimento para revisões de código para aplicar o padrão. Ah, e para encontrar erros também.

Algum bom e velho bom senso não iria mal; há muitos documentos padrão de codificação que trabalham em pontos irrelevantes (itens como tamanho e tipo de fonte são um dos mais extremos que já vi).

A melhor coisa a fazer se você estiver em um grupo de desenvolvedores é conversar um com o outro e olhar para o seu código, formar um consenso sobre o que é aceitável e se você precisar escrever os pontos principais como diretrizes, mas mantenha-os como apenas essas orientações. Se você não pode justificar qualquer divergência em relação às diretrizes, deve considerar realmente por que está fazendo isso.

No final do dia, um código claro e compreensível é mais importante do que qualquer regra rígida sobre layout ou tipografia.

Como outros já mencionaram, a cobertura do teste de código é importante. Eu também gosto de ver:

• Estrutura do projeto. Os testes fazem parte do código ou estão em um projeto / pacote / diretório separado? O código da interface do usuário vive com o material de back-end? Caso contrário, como é compartimentado?

• Processo de desenvolvimento. Escrever testes antes do código? A correção de compilações quebradas tem prioridade sobre o desenvolvimento? Quando são feitas as revisões de código e o que elas devem cobrir?

• Gerenciamento de código fonte. O que é verificado quando? Os documentos de design e os planos de teste são controlados por revisão? Quando você ramifica e quando etiqueta? Você mantém compilações anteriores e, em caso afirmativo, quantas / por quanto tempo?

• Padrões de implantação. Como uma compilação é empacotada? O que precisa ser incluído nas notas de versão? Como os scripts de atualização são criados / controlados / executados?

Esqueça toda essa porcaria sobre convenções de nomenclatura, formatação e quantas linhas podem estar em uma função / método / módulo. Uma regra: use o estilo existente no que você estiver editando. Se você não gosta do estilo de alguém, escolha-o em uma revisão de código. A única exceção pode ser a opção tabs-spaces, mesmo que muitos editores / IDEs se convertam cegamente um no outro e você acaba destruindo seu histórico de alterações porque todas as linhas foram alteradas.

Penso que há realmente duas coisas a tratar e, de fato, as consideraria separadamente, porque não podem ser abordadas da mesma maneira, embora eu ache as duas importantes.

• O aspecto técnico: que visa evitar código arriscado ou mal formado (mesmo que aceito pelo compilador / intérprete)
• O aspecto da apresentação: que se preocupa em tornar o programa claro para os leitores

O aspecto técnico que eu qualifico do Padrão de Codificação , assim como Herb Sutter e Andrei Alexandrescu, com seus Padrões de Codificação C ++ . A apresentação que eu qualifico do Estilo de codificação , que inclui convenção de nomes, recuo, etc ...

Padrão de codificação

Por ser puramente técnico, um Padrão de Codificação pode ser principalmente objetivo. Como tal, todas as regras devem ser suportadas por um motivo. No livro que me referi a cada item, temos:

• Um título, simples e direto ao ponto
• Um resumo, que explica o título
• Uma discussão, que ilustra a questão de fazer o contrário e, portanto, afirma a lógica
• opcional Alguns exemplos, porque um bom exemplo vale mais que mil palavras
• opcional Uma lista de exceções às quais esta regra não pode ser aplicada, às vezes com soluções alternativas
• Uma lista de referências (outros livros, sites) que discutiram este ponto

A justificativa e as exceções são muito importantes, pois resumem o porquê e quando.

O título deve ser explícito o suficiente para que, durante as revisões, seja necessário apenas uma lista de títulos (folhas de dicas) para trabalhar. E, obviamente, agrupe os itens por categoria para facilitar a procura por um.

Sutter e Alexandrescu conseguiram ter uma lista de apenas cem itens, mesmo que o C ++ seja considerado peludo;)

Estilo de codificação

Essa parte geralmente é menos objetiva (e pode ser totalmente subjetiva). A intenção aqui é garantir consistência, pois isso ajuda os mantenedores e os recém-chegados.

Você não deseja entrar em uma guerra santa sobre qual estilo de recuo ou chave é melhor aqui, há fóruns para isso: portanto, nessa categoria, você faz coisas por consenso> voto da maioria> decisão arbitrária do (s) líder (es).

Para um exemplo de formatação, consulte a lista de opções de Estilo Artístico . Idealmente, as regras devem ser claras e completas o suficiente para que um programa possa reescrever o código (embora seja improvável que você codifique um;))

Para a convenção de nomenclatura, eu tentaria distinguir classes / tipos facilmente de variáveis ​​/ atributos.

É também nesta categoria que classifico as "medidas" como:

• prefira métodos curtos a longos: geralmente é difícil concordar quanto tempo dura
• prefira retorno antecipado / continuar / interromper para reduzir o recuo

Misc?

E, como uma palavra final, há um item que raramente é discutido nos Padrões de Codificação, talvez porque seja específico de cada aplicativo: organização do código. A questão arquitetônica é talvez a mais destacada, estrague o design inicial e você será atormentado por isso daqui a alguns anos. Talvez você deva adicionar uma seção para tratamento básico de arquivos: cabeçalhos públicos / privados, gerenciamento de dependências, separação de interesses, interface com outros sistemas ou bibliotecas ...

Mas isso não é nada se não forem realmente aplicados e aplicados .

Qualquer violação deve ser apresentada durante as revisões de código e nenhuma revisão de código deve ser aceitável se uma violação estiver pendente:

• corrija o código para corresponder à regra
• corrija a regra para que o código não se destaque mais

Obviamente, mudar uma regra significa obter o "ir em frente" dos líderes.

Eu gosto do formato nas Diretrizes de design da estrutura que inclui uma seção geral e os fundamentos das diretrizes. A parte mais útil são os detalhes que começam com Não, Não, Evite e Considere.

Aqui está um exemplo na seção Implementando Membros da Interface Explicitamente, ele possui os seguintes itens (observe que deixei de lado as razões para a bervidade)

Evitar implementar explicitamente os membros da interface sem ter um forte motivo para fazê-lo

Considere implementar explicitamente os membros da interface se os membros tiverem que ser chamados apenas através da interface.

Não use membros explícitos como um limite de segurança.

Não fornecer um membro virtual protegido que oferece a mesma funcionalidade que o> membro explicitamente implementado se a funcionalidade destina-se a ser especializados por classes derivadas.

Isso cria um bom tom geral. Usando Evitar e Considerar, você pode permitir que os desenvolvedores usem seu julgamento. Também porque são diretrizes e não desenvolvedores de regras, provavelmente os acharão mais palatáveis ​​e, por sua vez, mais propensos a segui-los.

Parece que ninguém mencionou segurança - em um padrão de codificação, você deve ter referência a requisitos de código seguro (por exemplo, o uso de módulos de validação de entrada, desautorizando funções fracas conhecidas como strcpy, requisitos de manipulação de erros etc.)

Exemplos. Exemplos organizados, não triviais e próximos ao mundo real que fazem uso de todas as regras. Comentários (não necessariamente parte do código) que parte do exemplo segue qual regra.

Modelos. Não é do tipo C ++, mas é algo para copiar, colar e preencher ao vivo. É muito mais fácil obter esse comentário padrão de 24 linhas quando você tem uma referência para copiar.

Recurso número um: um máximo absoluto de duas páginas.

Isso é algo que você deseja que todo desenvolvedor leia e lembre-se. Você não deve procurar no padrão toda vez que precisar escrever uma nova função (ou pior, uma nova linha). Portanto, mantenha-o curto e mantenha apenas as regras que realmente agregam valor ao produto final.

Os padrões de codificação são realmente vários itens:

Convenções de codificação

• essas coisas não precisam de um motivo além da "consistência da base de código" para ex. usar '_' em variáveis ​​de membro privadas ou não.
• pode haver várias abordagens corretas. Só precisa escolher um para consistência. por ex. manipulação de erros usando exceções ou códigos de erro.

Melhores práticas

• esses itens sempre precisam de um bom motivo com alguns exemplos claros

por ex. Nunca deixe em branco Catch depois de tentar

try { Foo(); } catch { //do nothing }

1) Se houver uma exceção lançada por Foo (), isso poderá causar outros problemas nas funções a seguir, que supõem que o foo foi bem-sucedido.

2) O manipulador de erros global não notificará a equipe de suporte de exceção quando isso acontecer no prod

• abrange as práticas de "Codificação defensiva", como o uso de Asserts para testar suas suposições.

Ambiente de codificação

• ferramentas que toda a equipe usa. por ex. VS 2010, Resharper, Kiln, etc.

Os padrões de codificação, quando escritos em papel, são muito eficazes. Eu gosto de como o Go está publicando seu padrão de codificação. Possui a ferramenta gofmtpara formatar o texto do programa em um formato. Qualquer debate sobre o formato de codificação simplesmente resultará como um patch para as fontes de gofmt.

Quanto ao formato que deve ter,

• como nomear variáveis, macros, constantes, literais, funções, etc.
• como colocar {,}, (,), [,] quando se trata de ifcorpo da função, blocos de instrução para outros fins,
• quão larga deve ser a indentação,
• quantos caracteres uma linha de texto é permitida
• quantos níveis de recuos são permitidos antes que o código seja rejeitado / enviado para refatoração
• quantas linhas de código são permitidas por função antes de serem devolvidas para refatoração
• número máximo de argumentos que uma função pode receber antes de ser devolvida para refatoração
• Algumas linhas de comentários antes de uma função começar a explicar brevemente o que ela faz, se o corpo deve exceder uma página do código na tela; deixando como o objeto é alcançado no código no corpo da função

Quando estou lendo o código de outras pessoas (principalmente na linguagem C), se os nomes de variáveis ​​/ funções não forem intuitivos no contexto do projeto ou se excederem cinco níveis de recuo ou as funções exigirem mais de seis ou sete argumentos ou uma função for executada por mais de duas ou três páginas na tela, fica muito difícil ler e entender o código. Quando solicitado a realizar melhorias / trabalhos de manutenção, isso só aumenta a dificuldade. Isso me faz desejar gofmtque um programa seja escrito para cada projeto (ou mesmo idioma) e que todo arquivo de código-fonte seja executado nesse programa antes de ser confirmado no projeto.

Gosto do Google JavaScript Style Guide .

É conciso em suas diretrizes, mas tem detalhes se você precisar deles.

Código de auto-documentação (comentários, nomes de variáveis, nomes de funções etc.)