Convention d'annotation

1. [Obligatoire] Les commentaires sur les classes, les attributs de classe et les méthodes de classe doivent utiliser les spécifications Javadoc et utiliser le format /**contenu*/ La méthode // xxx n'est pas autorisée.

Remarque : Dans la fenêtre d'édition de l'IDE, le mode Javadoc demandera des commentaires pertinents, et le Javadoc généré peut afficher correctement les commentaires correspondants. Dans l'EDI, lorsque le projet appelle une méthode, vous pouvez survoler pour demander la méthode. , Paramètres, La signification de la valeur de retour améliore l'efficacité de la lecture.

2. [Obligatoire] Toutes les méthodes abstraites (y compris les méthodes dans les interfaces) doivent être annotées avec Javadoc En plus des valeurs de retour, des paramètres et des descriptions d'exception, vous devez également indiquer ce que fait la méthode et ce qu'elle implémente. . Fonction.

Remarque : Veuillez expliquer les exigences de mise en œuvre pour les sous-classes ou les précautions d'appel.

3. [Obligatoire] Toutes les classes doivent ajouter des informations sur le créateur.

4. [Obligatoire] Commentaires sur une seule ligne à l'intérieur de la méthode, commencez une nouvelle ligne au-dessus de l'instruction commentée et utilisez // comment. Commentaires multilignes dans les méthodes

Utilisez les commentaires /* */, faites attention à vous aligner sur le code.

5. [Obligatoire] Tous les champs de type énumération doivent comporter des commentaires pour expliquer le but de chaque élément de données.

6. [Recommandé] Plutôt que de commenter dans un anglais à moitié cuit, il est préférable d'utiliser des commentaires chinois pour expliquer clairement le problème. Les noms propres et les mots-clés peuvent rester dans le texte anglais original.

Contre-exemple : "Délai d'expiration de la connexion TCP" est interprété comme "Délai d'expiration de la connexion au protocole de contrôle de transmission", ce qui est plus difficile à comprendre.

7. [Recommandation] Lors de la modification du code, les commentaires doivent également être modifiés en conséquence, notamment les modifications des paramètres, des valeurs de retour, des exceptions, de la logique de base, etc.

.

Explication : Les mises à jour du code et des annotations sont désynchronisées, tout comme les mises à jour du réseau routier et du logiciel de navigation sont désynchronisées. Si le logiciel de navigation est sérieusement en retard, le sens de la navigation sera perdu.

8. [Référence] Le code commenté doit être accompagné d'instructions autant que possible, plutôt que simplement commenté.

Remarque :

Il y a deux possibilités lorsque le code est commenté : 1) La logique de ce code sera restaurée ultérieurement. 2) Ne l’utilisez jamais. S’il n’y a aucune information de remarque dans le premier, il est difficile de connaître la motivation de l’annotation. Il est recommandé de supprimer directement ce dernier (l'entrepôt de code enregistre le code historique).

9. [Référence] Exigences pour les commentaires : Premièrement, ils peuvent refléter avec précision les idées de conception et la logique du code ; Deuxièmement, ils peuvent décrire la signification commerciale, afin que les autres programmeurs puissent rapidement comprendre les informations derrière le code ; Une grande section de code sans aucun commentaire est comme un livre céleste pour le lecteur. Les commentaires sont à lire par soi-même, de sorte que l'on puisse comprendre clairement la pensée à ce moment-là, même après une longue période, les commentaires sont également à lire par les successeurs. afin qu'ils puissent rapidement reprendre votre travail. 10. [Référence] Une bonne structure de nom et de code est explicite et les commentaires doivent être concis, précis et expressifs. Évitez un extrême des commentaires : des commentaires trop nombreux et excessifs. Une fois la logique du code modifiée, modifier les commentaires sera une charge considérable.

Contre-exemple :

// put elephant into fridge
put(elephant, fridge);

Le nom de la méthode put, ainsi que deux noms de variables significatifs, éléphant et réfrigérateur, ont déjà expliqué ce que cela fait, et le code avec une sémantique claire ne nécessite pas de commentaires supplémentaires.

11. [Référence] Marque de commentaire spécial, veuillez indiquer la personne qui l'a noté et l'heure de la notation. Faites attention à traiter ces marques en temps opportun, parcourez les marques et nettoyez ces marques fréquemment. Les défauts en ligne proviennent parfois du code situé à ces marques.

1) Éléments à faire (
TODO

) : (marquer la personne, marquer le temps, [temps de traitement estimé])

représente une fonction qui doit être implémentée mais qui n'a pas encore été implémentée. Il s'agit en fait d'une balise Javadoc. Le Javadoc actuel n'a pas encore été implémenté, mais il est déjà largement utilisé. Ne peut être appliqué qu'aux classes, interfaces et méthodes (car il s'agit d'une balise Javadoc).

2) Erreur, ne peut pas fonctionner (FIXME

) : (marquer la personne, marquer le temps, [temps de traitement estimé])

Utilisez FIXME dans les commentaires pour marquer un certain code qui est faux, ne peut pas fonctionner, et doit être corrigé à temps.