Certaines des déclarations ci-dessous sont assez personnelles, bien qu'avec une certaine justification, et sont censées être de cette façon.
Types de commentaires
Pour la version courte ... J'utilise des commentaires pour:
- commentaires de fin expliquant les champs dans les structures de données (en dehors de ceux-ci, je n'utilise pas vraiment de commentaires sur une seule ligne)
- Commentaires multilignes exceptionnels ou orientés vers un objectif au-dessus des blocs
- documentation utilisateur et / ou développeur publique générée à partir de la source
Lisez ci-dessous pour les détails et les raisons (peut-être obscures).
Commentaires finaux
Selon la langue, en utilisant des commentaires sur une seule ligne ou des commentaires sur plusieurs lignes. Pourquoi cela dépend-il? C'est juste un problème de normalisation. Lorsque j'écris du code C, je préfère le code ANSI C89 à l'ancienne par défaut, donc je préfère toujours l'avoir /* comments */
.
Par conséquent, j'aurais cela en C la plupart du temps, et parfois (cela dépend du style de la base de code) pour les langages avec une syntaxe de type C:
typedef struct STRUCT_NAME {
int fieldA; /* aligned trailing comment */
int fieldBWithLongerName; /* aligned trailing comment */
} TYPE_NAME;
Emacs est sympa et fait ça pour moi avec M-;
.
Si le langage prend en charge les commentaires sur une seule ligne et n'est pas basé sur C, je serai plus enclin à utiliser les commentaires sur une seule ligne. Sinon, je crains d'avoir pris l'habitude. Ce qui n'est pas forcément mauvais, car cela m'oblige à être concis.
Commentaires multilignes
Je ne suis pas d'accord avec votre précepte d'utiliser des commentaires sur une seule ligne car cela est plus attrayant visuellement. J'utilise ceci:
/*
* this is a multi-line comment, which needs to be used
* for explanations, and preferably be OUTSIDE the a
* function's or class' and provide information to developers
* that would not belong to a generated API documentation.
*/
Ou ceci (mais je ne le fais plus souvent, sauf sur une base de code personnelle ou principalement pour des avis de droit d'auteur - c'est historique pour moi et vient de mon éducation. Malheureusement, la plupart des IDE le gâchent lors de l'utilisation du formatage automatique) :
/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/
Si besoin est, alors je commenterais en ligne en utilisant ce que j'ai mentionné plus tôt pour les commentaires de fin, s'il est logique de l'utiliser dans une position de fin. Sur un cas de retour très spécial, par exemple, ou pour documenter switch
les case
instructions de a (rare, je n'utilise pas souvent switch), ou lorsque je documente des branches dans un if ... else
flux de contrôle. Si ce n'est pas un de ceux-ci, généralement un bloc de commentaires en dehors de la portée décrivant les étapes de la fonction / méthode / bloc a plus de sens pour moi.
Je les utilise très exceptionnellement, sauf si le codage dans une langue sans prise en charge des commentaires de documentation (voir ci-dessous); auquel cas ils deviennent plus répandus. Mais dans le cas général, c'est vraiment juste pour documenter des choses qui sont destinées à d'autres développeurs et sont des commentaires internes qui doivent vraiment se démarquer. Par exemple, pour documenter un bloc vide obligatoire comme un bloc "forcé" catch
:
try {
/* you'd have real code here, not this comment */
} catch (AwaitedException e) {
/*
* Nothing to do here. We default to a previously set value.
*/
}
Ce qui est déjà moche pour moi mais je le tolérerais dans certaines circonstances.
Commentaires sur la documentation
Javadoc et al.
Je les utilise généralement sur les méthodes et les classes pour documenter les versions introduisant une fonctionnalité (ou la changer), surtout si c'est pour une API publique, et pour fournir des exemples (avec des cas d'entrée et de sortie clairs et des cas spéciaux). Bien que dans certains cas, un cas unitaire puisse être préférable pour les documenter, les tests unitaires ne sont pas nécessairement lisibles par l'homme (quel que soit le truc DSL que vous utilisez).
Ils me dérangent un peu pour documenter les champs / propriétés, car je préfère les commentaires de fin pour cela et tous les cadres de génération de documentation ne prennent pas en charge les commentaires de documentation de fin. Doxygen le fait, par exemple, mais pas JavaDoc, ce qui signifie que vous avez besoin d'un commentaire en haut pour tous vos champs. Je peux survivre à cela, car les lignes Java sont de toute façon relativement longues la plupart du temps, donc un commentaire de fin me ferait disparaître également en étendant la ligne au-delà de mon seuil de tolérance. Si Javadoc envisageait de l'améliorer, je serais bien plus heureux.
Code commenté
J'utilise une seule ligne pour une seule raison, dans des langages de type C (sauf si je compile pour un C strict, où je ne les utilise vraiment pas): pour commenter des trucs pendant le codage. La plupart des IDE devront basculer pour les commentaires sur une seule ligne (alignés sur le retrait ou sur la colonne 0), et cela correspond à ce cas d'utilisation pour moi. L'utilisation de la bascule pour les commentaires sur plusieurs lignes (ou la sélection au milieu des lignes, pour certains IDE) rendra plus difficile le basculement entre commentaire / décommentation facilement.
Mais comme je suis contre le code commenté dans le SCM, cela est généralement de très courte durée car je vais supprimer les morceaux commentés avant de valider. (Lisez ma réponse à cette question sur "les commentaires en ligne et les SCM modifiés" )
Styles de commentaire
J'ai généralement tendance à écrire:
- des phrases complètes avec une grammaire correcte (y compris la ponctuation) pour les commentaires de documentation, car elles sont censées être lues plus tard dans un document API ou même dans le cadre d'un manuel généré.
- bien formaté mais plus laxiste sur la ponctuation / majuscules pour les blocs de commentaires multilignes
- blocs de fin sans ponctuation (à cause de l'espace et généralement parce que le commentaire est bref, qui ressemble plus à une déclaration entre parenthèses)
Une note sur la programmation alphabétisée
Vous voudrez peut-être vous intéresser à la programmation littéraire , comme présenté dans cet article par Donald Knuth .
Le paradigme de programmation alphabétisé, [...] représente un abandon de l'écriture de programmes de la manière et de l'ordre imposés par l'ordinateur, et permet plutôt aux programmeurs de développer des programmes dans l'ordre exigé par la logique et le flux de leurs pensées. 2 Les programmes alphabétisés sont écrits comme une exposition ininterrompue de la logique dans un langage humain ordinaire, un peu comme le texte d'un essai [...].
Les outils de programmation alphabétisés sont utilisés pour obtenir deux représentations à partir d'un fichier source alphabétisé: une appropriée pour une compilation ou une exécution ultérieure par un ordinateur, le code "enchevêtré" et une autre pour la visualisation sous forme de documentation formatée, qui est dite "tissée" à partir de la source alphabétisée.
En guise de note secondaire et d'exemple: le cadre JavaScript underscore.js , nonobstant la non-conformité avec mon style de commentaire, est un assez bon exemple d'une base de code bien documentée et d'une source annotée bien formée - bien qu'il ne soit peut-être pas le meilleur à utiliser comme une référence API).
Ce sont des conventions personnelles . Oui, je pourrais être bizarre (et vous pourriez l'être aussi). C'est OK, tant que vous suivez et respectez les conventions de code de votre équipe lorsque vous travaillez avec des pairs, ou n'attaquez pas radicalement leurs préférences et ne cohabitez pas bien. Cela fait partie de votre style, et vous devriez trouver la fine ligne entre le développement d'un style de codage qui vous définit comme un codeur (ou comme un adepte d'une école de pensée ou d'une organisation avec laquelle vous avez un lien) et le respect de la convention d'un groupe pour la cohérence. .
:3,7 Align //
pour aligner les commentaires sur les lignes 3-7.