Google Style Guide en C ++. Partie 1

Partie 1. Introduction
...
Partie 8. Dénomination
Partie 9. Commentaires
...


Lors de l'écriture de code, nous utilisons tous les règles de conception du code. Parfois, leurs propres règles sont inventées, dans d'autres cas, des guides de style prêts à l'emploi sont utilisés. Bien que tous les programmeurs C ++ lisent plus facilement en anglais que dans leur langue maternelle, il est plus agréable d'avoir un manuel dans cette dernière.
Cet article est une traduction d'une partie du guide de style Google en C ++ en russe.
Article original (fork sur github), traduction mise à jour .
Ceci est la partie introductive du guide, qui aborde les questions générales de «Pourquoi?»
De plus, après la traduction, il y aura plusieurs réponses aux questions possibles.

Entrée

C ++ est l'un des principaux langages de programmation utilisés dans les projets Google open source. On sait que C ++ est un langage très puissant. Cependant, c'est un langage complexe et, s'il n'est pas utilisé correctement, il peut être un foyer de bogues, ce qui rend difficile la lecture et la maintenance du code.

L'objectif de ce guide est de gérer la complexité du code en décrivant en détail comment cela vaut la peine (ou pas la peine) d'écrire du code C ++. Les règles de ce guide simplifieront la gestion du code et augmenteront les performances des encodeurs.

Style - conventions suivies de code C ++. Le style est plus que le formatage d'un fichier avec du code.

La plupart des projets open source développés par Google suivent ce guide.

Remarque: ce guide n'est pas un didacticiel C ++: il est supposé que vous connaissez le langage.

Objectifs du guide de style

Pourquoi ce document est-il nécessaire?

Il y a plusieurs objectifs principaux de ce document, pourquoi interne, règles individuelles sous-jacentes. En utilisant ces objectifs, vous pouvez éviter de longues discussions: pourquoi les règles sont et pourquoi elles doivent être suivies. Si vous comprenez les objectifs de chaque règle, il vous est plus facile de les accepter ou de les rejeter, d'évaluer les alternatives lorsque vous modifiez les règles par vous-même.

Les objectifs de gestion sont les suivants:

• Les règles doivent valoir le changement.
  
  
  • Les avantages de l'utilisation d'un seul style devraient l'emporter sur l'insatisfaction des ingénieurs à se souvenir et à utiliser les règles.
  • L'avantage est évalué par rapport à la base de code sans application de règles, donc si vos employés n'appliquent toujours pas les règles, l'avantage sera très faible.
  • Ce principe explique pourquoi certaines règles manquent: par exemple, goto viole de nombreux principes, mais il n'est pratiquement pas utilisé, donc le Guide ne le décrit pas.
• Optimisé pour la lecture, pas pour l'écriture
  
  
  • Notre base de code (et la plupart de ses composants individuels) sera utilisée pendant longtemps. Par conséquent, beaucoup plus de temps sera consacré à la lecture de ce code qu'à l'écriture.
  • Nous nous soucions clairement que nos ingénieurs aient un lego pour lire, maintenir, déboguer le code. «Laisser le code de débogage / journalisation» est l'une des conséquences: lorsqu'un morceau de code fonctionne «bizarrement» (par exemple, lors du transfert de propriété d'un pointeur), la présence d'indices de texte peut être très utile ( std :: unique_ptr montre clairement le transfert de propriété).
• Écrire un code similaire à un code existant
  
  L'utilisation d'un style unique sur une base de code vous permet de passer à d'autres problèmes plus importants.
  
  De plus, un style unique favorise l'automatisation. Et, bien sûr, le formatage automatique du code (ou l'alignement de #include ) fonctionne correctement s'il répond aux exigences de l'utilitaire. Dans d'autres cas, un seul (le plus approprié) est utilisé dans l'ensemble de règles, et une certaine souplesse dans l'utilisation des règles permet aux gens de discuter moins.
• Écrire du code similaire à celui utilisé dans la communauté C ++ (si possible)
  
  La cohérence de notre code avec le code C ++ d'autres organisations et communautés est très utile. Si les fonctionnalités du C ++ standard ou les idiomes acceptés du langage facilitent l'écriture de programmes, c'est l'occasion de les utiliser. Cependant, les standards et les idiomes sont parfois mal adaptés à la tâche. Dans ces cas (comme décrit ci-dessous), il est logique de limiter ou d'interdire l'utilisation de certaines fonctionnalités standard. Dans certains cas, votre solution est créée, mais parfois des bibliothèques externes sont utilisées (au lieu de la bibliothèque C ++ standard) et la réécrire dans votre propre norme est trop coûteuse.
• Évitez les structures inattendues ou dangereuses.
  
  C ++ a des approches peu évidentes et même dangereuses. Certains styles de codage limitent leur utilisation, comme leur utilisation comporte de grands risques pour l'exactitude du code.
• Évitez les constructions que le programmeur C ++ moyen considère comme abusives et difficiles à prendre en charge
  
  En C ++, certaines fonctionnalités ne sont généralement pas les bienvenues en raison de la complexité du code.
  Cependant, dans le code fréquemment utilisé, l'utilisation de constructions délicates est plus justifiée en raison d'une utilisation répétée, ainsi que de nouvelles parties du code deviendront plus claires.
  
  En cas de doute, consultez le chef de projet.
  
  Ceci est très important pour notre base de code, car les propriétaires de code et une équipe d'assistance changent au fil du temps: même si tout le monde comprend le code maintenant, les choses peuvent changer en quelques années.
• Considérez l'échelle du code
  
  Avec une base de code de plus de 100 millions de lignes et des milliers d'ingénieurs, les erreurs et les simplifications peuvent être coûteuses. Par exemple, il est important d'éviter de salir l'espace de noms global: les collisions de noms sont très difficiles à éviter dans une grande base de code si tout est déclaré dans l'espace de noms global.
• Optimiser au besoin
  
  L'optimisation des performances est parfois plus importante que de suivre les règles de codage.

Le but de ce document est de fournir les conseils les plus compréhensibles avec des restrictions raisonnables. Comme toujours, personne n'a annulé le bon sens. Avec cette spécification, nous voulons établir des conventions pour l'ensemble de la communauté Google en C ++, pas seulement pour des équipes ou des personnes individuelles. Soyez sceptique vis-à-vis des designs rusés ou insolites: l'absence de limitation n'a pas toujours de résolution. Et si vous ne pouvez pas décider par vous-même, demandez au patron.

Version C ++

Maintenant, le code doit être conforme à C ++ 17, c'est-à-dire Les fonctionnalités C ++ 2x ne sont pas souhaitables. À l'avenir, le manuel sera adapté aux nouvelles versions de C ++.

N'utilisez pas d' extensions personnalisées .

Tenez compte de la compatibilité avec d'autres environnements si vous avez l'intention d'utiliser C ++ 14 et C ++ 17 dans votre projet.

Remarque: Les liens peuvent conduire à des sections du manuel qui n'ont pas encore été traduites.

Quelques réponses / commentaires:

- Pourquoi transférer?

Personnellement, je suis plus à l'aise avec les dirigeants russes. Il est également préférable de discuter des modifications du guide de style avec le texte russe.

- Pourquoi google? Y en a-t-il plus (ou moins) de populaires ...?

L'entreprise est assez connue, le leadership n'est pas très important (vous pouvez le traduire sans effort par une seule personne), il remplit les fonctions requises - ce guide est à la mode

- Mais le manuel de Google déclare l'utilisation de obsolètes (...), le rejet de tels utiles (...)! Pourquoi?

Si je comprends bien, ce document est une proposition. Vous allez utiliser quelque chose, changer quelque chose - c'est permis. Le leadership est une bonne base.