Java Conventions de commentaire
Quelle méthode de commentaire est la plus largement acceptée ou est-ce vraiment important?
J'utilise
/**
* (Method description)
* @param
* @return
* etc
*/
Cependant, j'ai lu:
Precondition:
Postcondition:
Existe-t-il une manière plus "professionnelle" de commenter?
Voici les conventions de codage Java pour les commentaires recommandés par Oracle:
Voici les recommandations de Google pour leur plate-forme Android:
Pour plus d'informations sur le style et les conventions de Javadoc, voir ici:
Tout d'abord, avoir du code lisible et des commentaires lisibles sont deux choses totalement différentes.
Le code lisible est un code qui utilise une bonne variable, une bonne méthode, des noms de classe, etc.
Les commentaires lisibles sont davantage une question de goût personnel. Certaines personnes aiment que les commentaires suivent des règles grammaticales qui seraient utilisées pour écrire un livre tandis que d'autres se moquent des choses grammaticales. Vous pouvez passer par ce lien:
http://www.Oracle.com/technetwork/Java/codeconventions-141999.html#385
À partir de code lisible et de commentaires, vous pouvez créer de la documentation à l'aide de doxygen.
Le style de commentaire dans votre premier exemple n'est pas seulement une convention, c'est un standard pour un outil de documentation appelé Javadoc . Si vous suivez ce style de commentaire Javadoc, vous pourrez facilement générer une documentation au format html pour tout votre code source.
Ce lien est très utile et je l'utilise depuis longtemps et m'a beaucoup aidé. Cela crée un code très bon et documenté avec une lisibilité maximale.
Je suivrais simplement la norme définie par Sun (Oracle) pour écrire Javadoc. Javadoc est référé à l'unanimité par tous les développeurs :). Pour plus d'informations, cliquez sur ici
Je vous demanderais également de faire ce qui suit recherche sur Stackoverflow pour de nombreuses questions et réponses sur les commentaires.