Pourquoi les blocs de commentaires /// sont-ils importants?
Quelqu'un a dit un jour que nous devrions préfixer toutes nos méthodes avec le /// <summary> blocs de commentaires (C #) mais n'a pas expliqué pourquoi.
J'ai commencé à les utiliser et j'ai trouvé qu'ils m'ennuyaient un peu, alors j'ai cessé de les utiliser, sauf pour les bibliothèques et les méthodes statiques. Ils sont volumineux et j'oublie toujours de les mettre à jour.
Y a-t-il une bonne raison d'utiliser /// <summary> des blocs de commentaires dans votre code?
J'utilise normalement // des commentaires tout le temps, c'est juste le /// <summary> blocs dont je me demandais.
tilisez-les autant que possible.
Oui, ce sont des commentaires spéciaux qui deviennent la documentation de la méthode. Le contenu de <summary>, les balises de paramètres, etc. générées s'affichent dans intellisense lorsque vous ou quelqu'un d'autre s'apprête à appeler votre méthode. Ils peuvent essentiellement voir toute la documentation de votre méthode ou classe sans avoir à aller dans le fichier lui-même pour comprendre ce qu'il fait (ou essayer de simplement lire la signature de la méthode et espérer le meilleur).
Oui, utilisez-les absolument pour tout ce que vous souhaitez conserver ou partager.
En outre, utilisez-les conjointement avec Sandcastle et Sandcastle Help File Builder , qui prend la sortie XML et la transforme en une belle documentation de style MSDN.
La dernière fois où j'ai travaillé, nous avons reconstruit la documentation tous les soirs et l'avons hébergée en tant que page d'accueil interne. Les initiales de la société étaient MF, donc c'était MFDN;)
Normalement, je produis juste un fichier .chm, qui est facilement partagé.
Vous seriez surpris de voir à quel point vous êtes accro à tout documenter une fois que vous commencez à le voir au format MSDN!
Si votre norme de codage exige que vous utilisiez de tels commentaires (et qu'une norme de codage pour une API ou un framework peut l'exiger), alors vous n'avez pas le choix, vous devez utiliser ces commentaires.
Sinon, pensez sérieusement à ne pas utiliser de tels commentaires. Vous pouvez les éviter dans la plupart des cas en modifiant votre code comme ceci:
/// <summary>
/// Checks if a user is authorized to access the resource
/// </summary>
public bool SecurityCheck( User user ) {
}
à
/// <summary>
/// Checks if a user is authorized to access the resource
/// </summary>
public bool IsAuthorizedToAccessResource( User user ) {
}
à
public bool IsAuthorizedToAccessResource( User user ) {
}
Le nom de votre classe, méthode et propriété doit être évident, donc si vous en avez besoin, c'est probablement une odeur.
Cependant, je recommanderais de les utiliser sur toutes les classes, méthodes et propriétés publiques dans une API, une bibliothèque, etc. pour les écrire.
Mais de toute façon, vous le découpez, les conservez ou les supprimez.
Si vous constatez que vous devez continuer à revenir en arrière et à modifier vos commentaires pour qu'ils correspondent au nouveau code, vous vous trompez peut-être en premier lieu. L'élément résumé doit contenir exactement cela - un résumé - le quoi et le pourquoi de la chose que vous résumez.
Décrire comment quelque chose fonctionne dans les commentaires viole DRY. Si votre code n'est pas suffisamment auto-descriptif, vous devriez peut-être revenir en arrière et refactoriser.
Oui, je les ai créés. [lors de la construction de nouveaux systèmes à partir de zéro]
Non, je n'en ai jamais profité. [lorsque vous travaillez sur des systèmes existants nécessitant une maintenance]
J'ai trouvé que les commentaires "Résumé" ont tendance à se désynchroniser avec le code. Et une fois que j'ai remarqué quelques commentaires qui se comportent mal, j'ai tendance à perdre confiance dans tous les commentaires sur ce projet - vous ne savez jamais à qui faire confiance.
Oublier de faire quelque chose n'en fait pas une mauvaise idée. Oublier de mettre à jour toute documentation est. Je les ai trouvés très utiles dans ma programmation et les personnes qui héritent de mon code sont reconnaissantes de les avoir.
C'est l'un des moyens les plus visibles de documenter votre code.
Il est difficile de trouver le code source pour lire la documentation en ligne ou de fouiller un document qui passe en revue ce que fait le code. Si vous pouvez faire apparaître quelque chose d'utile grâce à l'intelligence, alors les gens vous adoreront.
"Il doit être très utilisé, comme moi;)"
Je jouais avec des commentaires (///). Pour une classe, vous pouvez simplement faire un commentaire comme celui-ci
namespace test
{
/// <summary>
/// Summary description for Calendar.
/// </summary>
public partial class DatePicker : System.Web.UI.Page
{
Mais, pour une méthode, vous pouvez en ajouter plus en donnant une description des paramètres et des types de retour.
/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{
Vous pouvez utiliser un raccourci pour créer ce commentaire (///+Tab).
J'utilise l'équivalent en VB (puisqu'ils ne me laisseront pas utiliser C # - apparemment c'est trop dur ... pas de commentaire.) Je les trouve très pratiques. La plupart du temps j'attends jusqu'à la procédure ou la fonction est à peu près terminée avant de les insérer, ne serait-ce que pour éviter d'avoir à modifier les commentaires - ou à les avoir "désynchronisés".
Je n'écris pas nécessairement un roman - juste les bases, la description des paramètres et quelques remarques (généralement quand il y a quelque chose "hors de l'ordinaire" qui se passe là-dedans - solution de contournement ou autre merde que je préfère ne pas avoir dedans mais avoir pas de choix "pour l'instant".) (Ouais, je sais, que "pour l'instant" peut durer des années.)
Je suis très irrité par le code non commenté. Un consultant a écrit la version initiale de l'un de nos composants et n'a rien commenté et son choix de noms laisse à désirer ici et là. Il est parti depuis plus d'un an et nous sommes toujours en train de trier ses affaires (en plus de travailler sur nos propres affaires.)
les utiliser, sauf pour les bibliothèques
C'est le moment où ils sont utiles. Avec la génération de documentation XML activée et une référence à l'assembly, sans son projet, affichera plus de détails dans intellisense.
Mais pour les internes du projet actuel, ils se mettent juste en travers.
Je les utilise, mais comme d'autres l'ont dit pas universellement. Pour les petites méthodes, elles peuvent facilement être plus grandes que le code qu'elles expliquent. Ils sont très utiles pour générer de la documentation qui peut être donnée aux personnes nouvelles dans le système afin qu'elles aient quelque chose à consulter tout en l'apprenant. Même si, en tant que programmeurs, nous pouvons généralement découvrir ce qu'est un code car il est agréable d'avoir les commentaires pour nous guider et agir comme une béquille. S'il a doit être écrit quelque part, alors dans le code est l'endroit où il est le plus susceptible de rester à jour (plus probable que certains documents Word flottant).