Criando um documento de padrões de codificação

Eu trabalho em uma empresa de sistemas de controle, onde o trabalho principal é SCADA e PLC , juntamente com outras coisas de sistemas de controle.

O desenvolvimento de software não é realmente algo que a empresa faz, além de pequenos detalhes aqui e ali, até que houve uma decisão de criar um sistema interno de gerenciamento e avaliação de projetos.

Este projeto foi assumido por pessoas que vieram aqui como pessoas de software originalmente e somos principalmente juniores.

O projeto começou pequeno, então apenas documentamos coisas como design, material de banco de dados etc., mas nunca concordamos com um formato / convenções de codificação.

Começamos a usar o StyleCop para garantir que tivéssemos um código bem documentado, mas acho que precisamos de um documento oficial para convenções / práticas de codificação, para que possamos continuar com um bom padrão e se houver mais trabalho de desenvolvimento importante no futuro, quem trabalha nele tem uma boa placa de base.

Aí reside o problema, não tenho idéia de como redigir um documento para convenções e padrões de codificação, tudo o que consigo pensar são exemplos de boas e más práticas (por exemplo, caso de camelo ao nomear variáveis, evitando a notação húngara, etc.) programadores competentes o suficiente (aparentemente), mas simplesmente não temos um termo para esse tipo de coisa.

Para colocar um ponto, minha pergunta é: Quais são os principais aspectos e conteúdo de um bom documento sobre padrões de codificação?

Quais são os principais aspectos e conteúdo de um bom documento sobre padrões de codificação?

1. Ser apoiado por ferramentas que permitem a verificação automatizada do código . Se eu souber que não posso me comprometer com o controle de versão de nenhum trecho de código que não corresponda a algumas regras, eu seria incentivado a seguir essas regras no meu código. Se, por outro lado, algum colega programador escreveu em algum lugar que eu preciso seguir uma regra, não dou a mínima para essas regras.

2. Ser bem pensado, em vez de ser sua opinião pessoal . Você não diz claramente: "a partir de agora, não usamos mais regiões, porque não gosto de regiões". Em vez disso, você explicaria que as regiões incentivam o crescimento do código e não resolvem nenhum grande problema .

   O motivo é que, no primeiro caso, seu colega responderia: "bem, eu gosto de regiões, então ainda as usaria". No segundo caso, por outro lado, forçaria as pessoas que discordam a receber críticas, sugestões e argumentos construtivos, fazendo com que você mude sua opinião original.

3. Sendo bem documentado . A falta de documentação cria confusão e espaço para interpretação ; confusão e possibilidade de interpretação levam à diferença de estilo, ou seja, a coisa que os padrões desejam suprimir.

4. Ser difundido, inclusive fora da sua empresa . Um "padrão" usado por vinte programadores é menos padrão do que o conhecido por centenas de milhares de desenvolvedores em todo o mundo.

Como você está falando do StyleCop, suponho que o aplicativo seja escrito em uma das linguagens do .NET Framework.

Nesse caso, a menos que você tenha motivos sérios para fazer diferente, basta seguir as diretrizes da Microsoft. Existem vários benefícios em fazê-lo, em vez de criar seus próprios padrões. Tomando os quatro pontos anteriores:

1. Você não precisa reescrever as regras do StyleCop para ajustar-se aos seus próprios padrões. Não digo que seja difícil escrever suas próprias regras, mas se você puder evitar, significa que você terá mais tempo fazendo algo útil.

2. As diretrizes da Microsoft são muito bem pensadas. Há chances de que, se você não concorda com alguns deles, talvez seja porque você não os entende. Este foi exatamente o meu caso; Quando iniciei o desenvolvimento de C #, achei algumas regras totalmente estúpidas. Agora, concordo plenamente com eles, porque finalmente entendi por que eles foram escritos dessa maneira.

3. As diretrizes da Microsoft estão bem documentadas, portanto você não precisa escrever sua própria documentação.

4. Novos desenvolvedores que serão contratados em sua empresa mais tarde já devem estar familiarizados com os padrões de codificação da Microsof. Há algumas chances de que ninguém esteja familiarizado com o seu estilo de codificação interno.

A primeira coisa importante a ser observada é que um documento de padrões de codificação não é sobre certo e errado. Não se trata de bom e ruim ou qual método é melhor.

O objetivo de um documento de padrões de codificação é garantir que todo o código seja projetado, escrito e definido da mesma maneira, para facilitar o desenvolvimento de um desenvolvedor de uma pessoa para outra sem a mudança de mentalidade necessária para ler o estilo de outra pessoa.

É tudo uma questão de uniformidade, e nada sobre "Certo e errado"

Com isso em mente, algumas coisas que você deve esclarecer em um documento sobre padrões de codificação são:

Convenções de nomenclatura

Como você nomeará seus métodos, variáveis, classes e interfaces? Qual notação você usará?

Além disso, outra coisa incluída em nossos padrões era a separação de padrões para SQL; portanto, tínhamos nomes semelhantes para tabelas, procedimentos, colunas, campos de identificação, gatilhos etc.

Indentação

O que você usará para indentação? Uma única guia? 3 espaços?

Layout

As chaves serão mantidas na mesma linha que a linha do método de abertura? (geralmente java) ou na próxima linha ou em uma linha própria? (geralmente C #)

Manuseio / registro de exceções

Quais são os seus padrões para manipulação e registro de exceções, é tudo feito em casa ou você está usando uma ferramenta de terceiros? Como deve ser usado?

Comentando

Temos padrões para determinar a correção gramatical, e esses comentários começam na linha antes ou depois da mesma linha, isso aumenta a legibilidade. Os comentários terão que ser recuados com a mesma profundidade do código? Você aceita as bordas dos comentários usadas em textos maiores?

Que tal o \\\ on Methods para descrições? Estes devem ser usados? Quando?

Exposição

Todos os seus métodos e campos devem estar implementando o nível mais baixo de acesso possível?

Também é uma coisa importante a se notar. Um documento de bons padrões pode ajudar bastante na revisão do código, ele atende a esses padrões mínimos?

Eu mal arranhei a superfície do que pode entrar em um desses documentos, mas o KISS

Não demore muito, seja entediante e impossível de passar, ou esses padrões simplesmente não serão seguidos, mantenha-o simples.

Eu estava passando por esse processo várias vezes. E a abordagem mais bem-sucedida (embora instável de qualquer maneira) foi pegar o documento "Padrões de codificação" de uma empresa conhecida e modificá-lo para atender às suas necessidades.

Por exemplo, eu encontrei este aqui: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

De qualquer forma, mantenha seu lança-chamas à mão.

Felicidades,

Eu odeio a maioria dos documentos de normas, pois eles geralmente tentam suar as coisas pequenas e ignorar o quadro geral.

Por exemplo, quase todos dirão como nomear variáveis ​​ou colocar colchetes. Este é um estilo puro e faz pouco para realmente ajudar um grupo de códigos de desenvolvedores corretamente. Eles ignoram coisas como estrutura de diretórios e layout de código. Vi documentos de padrões que informavam exatamente quantos espaços colocar entre operadores e quantas linhas em branco colocavam entre métodos. Tudo isso geralmente termina com uma tonelada de exceções à regra, que apenas mostra o quão inútil elas realmente são, e então são tão grandes que ninguém pode segui-las, o que novamente zomba do argumento que elas estão tentando fazer. .

Agora, para mim, eu uso muitos bits diferentes de software de muitas pessoas diferentes e todos eles têm estilos diferentes. Eu simplesmente me acostumei com isso, não reclamo que não existe um estilo comum em todos os grupos de desenvolvimento. Desde que o código seja um estilo comum em todo o projeto, eu realmente não me importo com esse estilo. Portanto, minha primeira regra para todos os documentos de normas é: Manter um estilo de codificação consistente no projeto . ninguém deve dar um figo onde estão os suportes, desde que sejam todos iguais. Pegue as guerras religiosas e empurre-as :)

O segundo é o layout do código. Quando pego um pedaço de código, quero ver que ele é apresentado em linhas semelhantes a outras peças de trabalho semelhantes. Se eu tiver um serviço da Web, desejo que o nome do contrato wsdl fique claro, desejo que o nome da implementação fique claro. Não quero que alguém crie um layout novo e diferente para arquivos e classes. Isso significa que eu tenho que jogar "caçar o código", o que é um incômodo. Se parecer igual ao último projeto em que trabalhei, posso saber imediatamente onde encontrar o que estou procurando e provavelmente é a maior ajuda para trabalhar com o código de outras pessoas que eu conheço. Portanto, mantenha uma estrutura de como o código é organizado (por exemplo, pasta Documentação para documentos, interfaces para interfaces etc - seja lá o que for que funciona para você, mas mantenha-o).

Os artefatos de código também devem estar presentes, portanto, você precisa dizer se o tratamento de erros esperado é uma exceção ou um código de erro - por exemplo. documentar a funcionalidade arquitetônica em uso . Também deve dizer que tipo de log usar e como apresentar a manipulação de logs / erros ao usuário ou qualquer subsistema usado para gerenciar o código em estado selvagem. Eu trabalhei em um local em que todos os projetos registravam diferentemente - era patético como cada versão do código tinha que ter seu próprio documento de operações, diferente, informando aos operadores como saber se havia errado. Log de eventos, arquivo de log (nesse caso, onde) etc. são todos válidos aqui. O mesmo se aplica a outros aspectos comuns do código - como configurá-lo (não faz sentido usar um arquivo .config para alguns programas ou um banco de dados personalizado, parâmetros de linha de comando ou registro para outros).

Em suma, a única coisa que importa é a consistência . E como documentos de grandes padrões são demais para ler e memorizar, prefiro simplesmente informar as pessoas sobre o que elas não podem ver (por exemplo, padrões de arquitetura, como registro em log) e dizer-lhes para manter o código que eles escrevem consistente com o que existe atualmente. E se você ainda não possui código, não precisa de um documento de padrões! (bem, não até que você tenha escrito o suficiente para torná-lo útil).

Portanto, retire daí os principais pontos: não tente criar um documento legal , pense em coisas que não estão apenas codificando, mas também como o código funciona e como ele se ajusta às expectativas de outras pessoas. Então confie nas pessoas para fazer um bom código e você verá que elas fazem. (e se não o fizerem, você pode ter palavras com eles, não há necessidade de defini-lo como lei).

Não, é um total desperdício de tempo e energia. O StyleCop é excelente e foi estabelecido ao longo de anos por pessoas muito mais experientes e muito mais inteligentes do que você ou qualquer pessoa da sua equipe. Abrace e ame! Ele o orienta continuamente, o que é melhor do que qualquer documento aguardando alguém que possa se incomodar em lê-lo.