Recently have been going through some old code to review the comments in them from other developers and what I find out is developers tend to have really bad comments & documentation in their code
Example:
|
1 2 3 4 5 6 7 8 |
public class Person { /// <summary> /// Constructor /// </summary> public Person() {} } |
From the above code it is obvious that it is the constructor but does the comment tell me anything? I understand that sometimes it may be hard to document or comment certain method, thus I really strongly suggest at least use GhostDoc
What is GhostDoc?
GhostDoc is a Visual Studio extension that automatically generates XML documentation comments for methods and properties based on their type, parameters, name, and other contextual information.
Here is the result of using GhostDoc on the Person Class
|
1 2 3 4 5 6 7 |
public class Person { /// <summary> /// Initializes a new instance of the <see cref="Person"/> class. /// </summary> public Person() {} } |
As one can see Ghostdoc does a better job, don’t get me wrong GhostDoc still requires one to go through the comments here is an example where it tries to make sense.
|
1 2 3 4 5 |
/// <summary> /// Riches the text selection changed. /// </summary> /// <param name="richTextBox">The rich text box.</param> private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) |
Riches the text selection changed. ????? As you can see it didn’t do one of the best job for this comment, but at least one can modify it and it may become “RichTextBox selection has changed event handler”
Personally I would recommend using the tool but just take it with a grain of salt and always check the documentation that it generates.
Leave A Comment