Code Java commentaires des meilleures pratiques
J'ai finalisé mon Java/Android projet et maintenant, j'ai besoin de commenter les codes (principalement les classes et méthodes).
J'ai besoin de le faire en suivant les meilleurs standards industriels comme plus tard si quelqu'un d'autre le besoin de le modifier, il doit être bien straight forward.
J'ai lu de nombreux articles et a trouvé 3 principaux types de java, en commentant les styles.
- Commentaire d'une ligne (//.....)
- Bloquer les commentaires (/* ....... */)
- Doc commentaires (/** ....... */)
J'ai lu principalement sur l'option 2 et 3. Un débordement de pile discussions
Alors j'ai pensé à aller à la 2ème option que je n'ai pas besoin de générer du HTML docs que ces classes ne vont pas à utiliser par tous les autres gens, et c'est la mise en œuvre de cette application.
Se demander quelles sont les meilleures pratiques dans le bloc de commentaires indiquant "retour", "paramètres" et "obtenir de brèves description" de la méthode ou de la classe.
Aimerions connaître les meilleures pratiques standard de l'industrie de la code java commentaires.
Merci d'avance...!!!
juste assez, commentaire supprimé.
OriginalL'auteur JibW | 2014-04-03
Vous devez vous connecter pour publier un commentaire.
Je vous recommande d'aller avec la 3ème option, parce que si quelqu'un regarde votre code par exemple, une IDE qui prend en charge la documentation Javadoc (par exemple, Eclipse), il va montrer de l'information pertinente sur les objets qu'il/elle examine quand il/elle passe sur un élément qui l'intéresse lui/elle.
De cette façon, le développeur n'aura pas à la classe réelle fichier de source pour comprendre ce que le contrat de l'est, que fait-il, ou peut-être des Exceptions vous devez faire attention lorsque vous l'utilisez.
Vous pouvez lier des classes/méthodes par JavaDOC crochets comme @voir.
Personnellement, je préfère mettre en DOC commentaires au moins sur ma classe, et les méthodes public, privé méthodes je n'ai pas l'habitude de voir une grande utilité pour les DOC des commentaires, car je n'ai pas l'habitude de générer la JavaDOC HTML. Autres que le DOC commentaires j'ai l'habitude ont tendance à utiliser les commentaires d'une ligne, et utiliser uniquement le bloc de commentaires quand j'ai envie d'1 phrase ne sera pas suffisant pour exprimer ce que je voulais, ou lorsque la marge d'impression, les restrictions entrent en jeu.
Le point est que vous avez demandé à propos de industrie standard. Vos collègues développeurs sont vous permettant de savoir comment d'autres en plus vous-même vous attendez à voir dans le code source. Une autre façon est de consulter les projets open source qui ont des commentaires à suivre leur pratique. Doc style certainement la meilleure façon pour les descriptions d'un morceau de code et la ligne de style est le meilleur pour les éléments uniques dans ces morceaux.
OriginalL'auteur Ceiling Gecko
Pour l'explication sur l'utilisation de l'API javadoc /** ... */
Pour les explications à l'intérieur du code d'utilisation //
Pour commenter plusieurs lignes de code d'utilisation /* ... */
OriginalL'auteur Pavel Bernshtam
Utiliser le Javadoc standard avec la javadoc tag conventions (3e option). Pourquoi:
La première et la deuxième option est plus pour des commentaires directement sur les lignes de code. Pas pour la description des classes et des méthodes.
OriginalL'auteur VinZ