Documentation via Code Comments
-
Sadly no! I am looking at some third party component/control documentation which seem to have been generated by Sandcastle or NDoc. Though the layout looks good, navigation is easy but the documentation itself sucks. So I looked at the XML documentation I was writing. Same issues!
/// <summary>
/// Initializes a new instance of ImpactCalculation
/// </summary>
public ImpactCalculation()
{
this.Lines = new ImpactCalculationLineCollection(this);
}Is documentation via code comments a flawed idea? I think so more and more. The most useful documentation I have seen or have written has never been generated from code comments. So what is your solution to the documentation problem? Or what is the most useful documentation you have seen/created and how did you create it?
You have, what I would term, a very formal turn of phrase not seen in these isles since the old King passed from this world to the next. martin_hughes on VDK
I hate code comments. I use them, but I hate them. I'd rather be able to attach the documenation, effectively, as a layer. I've often thought of writing an add-in for Visual Studio that would put the documentation onto a layer of its own in the same way that you can layer things in Photoshop. It would be great if you could have a method (we'll call it InitializeFactory, and have the documentation associated with it as a property. I'm not sure I'm explaining it properly, but I could see you clicking on the method header and the property would appear in the property grid - I'll try blocking it out here:
public static void InitializeFactory(int value)
|------------------------------------------------------------|
| General |
|------------------------------------------------------------|
| Name | InitializeFactory |
| Summary | This method is used to initialize the class |
| | factory to a particular value |
| Returns | None |
|------------------------------------------------------------|
| Parameters |
|------------------------------------------------------------|
| value | The initial value to set the factory to. |
|------------------------------------------------------------|Well, you get the general idea. No more documentation cluttering code, and documentation managed in a neat and easy manner. BTW - the name value in the summary links to the relevant item in the parameters section.
Deja View - the feeling that you've seen this post before.
-
Sadly no! I am looking at some third party component/control documentation which seem to have been generated by Sandcastle or NDoc. Though the layout looks good, navigation is easy but the documentation itself sucks. So I looked at the XML documentation I was writing. Same issues!
/// <summary>
/// Initializes a new instance of ImpactCalculation
/// </summary>
public ImpactCalculation()
{
this.Lines = new ImpactCalculationLineCollection(this);
}Is documentation via code comments a flawed idea? I think so more and more. The most useful documentation I have seen or have written has never been generated from code comments. So what is your solution to the documentation problem? Or what is the most useful documentation you have seen/created and how did you create it?
You have, what I would term, a very formal turn of phrase not seen in these isles since the old King passed from this world to the next. martin_hughes on VDK
Rama Krishna Vavilala wrote:
/// /// Initializes a new instance of ImpactCalculation///
I guess it partly matters what else is there. If that is all there is in the code not much more can be said, but you better say a lot more in the class description.
/// <summary> /// The Impact calculation class handles the 3d probalistic calculation of a moving /// body to a possible impact location on the surface of the earth. Calculations are /// employed using ... and ... with filter model ... and prediction model ... /// reference papers, algorithms, authors, speed of algorithm, choices of models, etc. /// </summary> public class ImpactCalculation { /// <summary> /// Initializes a new instance of ImpactCalculation using default data to ... conditions /// </summary> public ImpactCalculation() { this.Lines = new ImpactCalculationLineCollection(this); } /// <summary> /// Initializes a new instance of ImpactCalculation using ... by calculating ... using ... algorithm /// </summary> public ImpactCalculation(params...) { this.Lines = new ImpactCalculationLineCollection(this); }_________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
Sadly no! I am looking at some third party component/control documentation which seem to have been generated by Sandcastle or NDoc. Though the layout looks good, navigation is easy but the documentation itself sucks. So I looked at the XML documentation I was writing. Same issues!
/// <summary>
/// Initializes a new instance of ImpactCalculation
/// </summary>
public ImpactCalculation()
{
this.Lines = new ImpactCalculationLineCollection(this);
}Is documentation via code comments a flawed idea? I think so more and more. The most useful documentation I have seen or have written has never been generated from code comments. So what is your solution to the documentation problem? Or what is the most useful documentation you have seen/created and how did you create it?
You have, what I would term, a very formal turn of phrase not seen in these isles since the old King passed from this world to the next. martin_hughes on VDK
In the agile methodology the properly written code should be enough to infer the comments. If the comments can be inferred then there is no point in writing them. Comments should describe things that cannot be inferred from the code. Like, what was the author thinking, why this using a for loop instead of foreach. Pre conditions, post conditions, known side effects. Potential errors. Generated documentation inferred from source is one of the stupidest ideas in modern software engineering. End rant
Need a C# Consultant? I'm available.
Happiness in intelligent people is the rarest thing I know. -- Ernest Hemingway -
In the agile methodology the properly written code should be enough to infer the comments. If the comments can be inferred then there is no point in writing them. Comments should describe things that cannot be inferred from the code. Like, what was the author thinking, why this using a for loop instead of foreach. Pre conditions, post conditions, known side effects. Potential errors. Generated documentation inferred from source is one of the stupidest ideas in modern software engineering. End rant
Need a C# Consultant? I'm available.
Happiness in intelligent people is the rarest thing I know. -- Ernest HemingwayBut there's a difference between comments and documentation. Code Comments tend to blur this - you're either generating documentation or you're commenting. They aren't the same thing - so don't try to make them the same.
Deja View - the feeling that you've seen this post before.
-
But there's a difference between comments and documentation. Code Comments tend to blur this - you're either generating documentation or you're commenting. They aren't the same thing - so don't try to make them the same.
Deja View - the feeling that you've seen this post before.
XML Commenting does try to blur the distinction. As such look at the poor quality of MSDN these days. Embarrassing really.
Need a C# Consultant? I'm available.
Happiness in intelligent people is the rarest thing I know. -- Ernest Hemingway -
But there's a difference between comments and documentation. Code Comments tend to blur this - you're either generating documentation or you're commenting. They aren't the same thing - so don't try to make them the same.
Deja View - the feeling that you've seen this post before.
what if my outside the app text document has code snippets with comments... :->
-
Sadly no! I am looking at some third party component/control documentation which seem to have been generated by Sandcastle or NDoc. Though the layout looks good, navigation is easy but the documentation itself sucks. So I looked at the XML documentation I was writing. Same issues!
/// <summary>
/// Initializes a new instance of ImpactCalculation
/// </summary>
public ImpactCalculation()
{
this.Lines = new ImpactCalculationLineCollection(this);
}Is documentation via code comments a flawed idea? I think so more and more. The most useful documentation I have seen or have written has never been generated from code comments. So what is your solution to the documentation problem? Or what is the most useful documentation you have seen/created and how did you create it?
You have, what I would term, a very formal turn of phrase not seen in these isles since the old King passed from this world to the next. martin_hughes on VDK
"Documentation from Comments" will not improve your documentation, it will just couple the location, so it makes keeping them in sync somewhat easier. I think XML comments are a flawed idea - XML is redundant and ugly to read. Using "code from comments" you have to balance readability in source code vs. elegance of the generated docs a bit, and all that XML crap makes this harder. Suggestion: Use a wiki, and link your code to it using Linkify[^].
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
blog: TDD - the Aha! | Linkify!| FoldWithUs! | sighistmodified on Friday, February 01, 2008 2:57:49 AM
-
"Documentation from Comments" will not improve your documentation, it will just couple the location, so it makes keeping them in sync somewhat easier. I think XML comments are a flawed idea - XML is redundant and ugly to read. Using "code from comments" you have to balance readability in source code vs. elegance of the generated docs a bit, and all that XML crap makes this harder. Suggestion: Use a wiki, and link your code to it using Linkify[^].
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
blog: TDD - the Aha! | Linkify!| FoldWithUs! | sighistmodified on Friday, February 01, 2008 2:57:49 AM
-
Sadly no! I am looking at some third party component/control documentation which seem to have been generated by Sandcastle or NDoc. Though the layout looks good, navigation is easy but the documentation itself sucks. So I looked at the XML documentation I was writing. Same issues!
/// <summary>
/// Initializes a new instance of ImpactCalculation
/// </summary>
public ImpactCalculation()
{
this.Lines = new ImpactCalculationLineCollection(this);
}Is documentation via code comments a flawed idea? I think so more and more. The most useful documentation I have seen or have written has never been generated from code comments. So what is your solution to the documentation problem? Or what is the most useful documentation you have seen/created and how did you create it?
You have, what I would term, a very formal turn of phrase not seen in these isles since the old King passed from this world to the next. martin_hughes on VDK
What makes you think that the person that wrote that comment wouldn't write the same thing in a separate documentation? Comment documentation can be excellent but it all depends upon the writer as with anything else. I prefer comment documentation generated directly off the library because it's easy to generate and therefore usually always up to date, I think it's an excellent idea and I think it's absurd to think the idea itself is bad because someone somewhere badly implemented it.
When everyone is a hero no one is a hero.
-
I hate code comments. I use them, but I hate them. I'd rather be able to attach the documenation, effectively, as a layer. I've often thought of writing an add-in for Visual Studio that would put the documentation onto a layer of its own in the same way that you can layer things in Photoshop. It would be great if you could have a method (we'll call it InitializeFactory, and have the documentation associated with it as a property. I'm not sure I'm explaining it properly, but I could see you clicking on the method header and the property would appear in the property grid - I'll try blocking it out here:
public static void InitializeFactory(int value)
|------------------------------------------------------------|
| General |
|------------------------------------------------------------|
| Name | InitializeFactory |
| Summary | This method is used to initialize the class |
| | factory to a particular value |
| Returns | None |
|------------------------------------------------------------|
| Parameters |
|------------------------------------------------------------|
| value | The initial value to set the factory to. |
|------------------------------------------------------------|Well, you get the general idea. No more documentation cluttering code, and documentation managed in a neat and easy manner. BTW - the name value in the summary links to the relevant item in the parameters section.
Deja View - the feeling that you've seen this post before.
Pete O'Hanlon wrote:
I've often thought of writing an add-in for Visual Studio that would put the documentation onto a layer of its own in the same way that you can layer things in Photoshop.
I've often thought it'd be nice to use something like that...so if you wrote it, you'd be guaranteed at least one user :-)
-
I hate code comments. I use them, but I hate them. I'd rather be able to attach the documenation, effectively, as a layer. I've often thought of writing an add-in for Visual Studio that would put the documentation onto a layer of its own in the same way that you can layer things in Photoshop. It would be great if you could have a method (we'll call it InitializeFactory, and have the documentation associated with it as a property. I'm not sure I'm explaining it properly, but I could see you clicking on the method header and the property would appear in the property grid - I'll try blocking it out here:
public static void InitializeFactory(int value)
|------------------------------------------------------------|
| General |
|------------------------------------------------------------|
| Name | InitializeFactory |
| Summary | This method is used to initialize the class |
| | factory to a particular value |
| Returns | None |
|------------------------------------------------------------|
| Parameters |
|------------------------------------------------------------|
| value | The initial value to set the factory to. |
|------------------------------------------------------------|Well, you get the general idea. No more documentation cluttering code, and documentation managed in a neat and easy manner. BTW - the name value in the summary links to the relevant item in the parameters section.
Deja View - the feeling that you've seen this post before.
I want this bad ! Would this be stored separately from the source file ?
-
Fixored! :-O
We are a big screwed up dysfunctional psychotic happy family - some more screwed up, others more happy, but everybody's psychotic joint venture definition of CP
blog: TDD - the Aha! | Linkify!| FoldWithUs! | sighist -
Sadly no! I am looking at some third party component/control documentation which seem to have been generated by Sandcastle or NDoc. Though the layout looks good, navigation is easy but the documentation itself sucks. So I looked at the XML documentation I was writing. Same issues!
/// <summary>
/// Initializes a new instance of ImpactCalculation
/// </summary>
public ImpactCalculation()
{
this.Lines = new ImpactCalculationLineCollection(this);
}Is documentation via code comments a flawed idea? I think so more and more. The most useful documentation I have seen or have written has never been generated from code comments. So what is your solution to the documentation problem? Or what is the most useful documentation you have seen/created and how did you create it?
You have, what I would term, a very formal turn of phrase not seen in these isles since the old King passed from this world to the next. martin_hughes on VDK
I find this a question of consistency. Sometimes 'Initializes a new instance' is all you can say, because it's all the constructor does, but I'd rather do that than have 'missing' constructor documentation.
-
Pete O'Hanlon wrote:
I've often thought of writing an add-in for Visual Studio that would put the documentation onto a layer of its own in the same way that you can layer things in Photoshop.
I've often thought it'd be nice to use something like that...so if you wrote it, you'd be guaranteed at least one user :-)
Hmmmm. I feel there's a niche market here.
Deja View - the feeling that you've seen this post before.