I used to use GhostDoc, but I found this new tool by Atomineer that makes the comments look much better (good for production code). This documenting package also documents you source file and works with C++ and C code (as well as C#). It is also available via the Tools dropdown menu within the Visual Studio IDE
At the start of the file (line 1), I can have Atomineer add the following comment:
////////////////////////////////////////////////////////////////////////////////////////////////////
// project: DragAndDropOfImage
// file: DragAndDropOfImage\Form1.cs
//
// summary: Implements the form 1 class
//
// Copyright (c) 2011 My Coompany Inc. All rights reserved.
////////////////////////////////////////////////////////////////////////////////////////////////////
using System;
using System.Drawing;
using System.Windows.Forms;
The class level documenting is as such:
namespace DragAndDropOfImage
{
////////////////////////////////////////////////////////////////////////////////////////////////////
/// Form 1.
///
/// My Developer Name, 11/22/2011.
////////////////////////////////////////////////////////////////////////////////////////////////////
public partial class Form1 : Form
{...}
And, each function as:
////////////////////////////////////////////////////////////////////////////////////////////////////
/// Event handler. Called by panel for drag enter events.
///
/// .
///
/// Source of the event.
/// Drag event information.
////////////////////////////////////////////////////////////////////////////////////////////////////
private void panel_DragEnter(object sender, DragEventArgs e)
{...}
There are many more functions available that I haven't yet explored. The help is quite complete and useful. Also, you can set how your comments are formed in a configuration file (see the help about this). And, there is an options setup dialog where you can further make changes in the settings. For more information, go to http://www.atomineerutils.com.
Discussion on:
View:
Show:
It looks like all the comments are simply re-stating the function definitions in English. Since that information is obvious to a programmer, I don't really see the point of this sort of comment.
I know it's common practice for some to fill their code with this sort of duplicated information, but I find it just makes it harder to see the logic of the code. It's like the standard Java doco pages. A bland listing of member functions and objects is useless without details of how it is used and what the functions actually accomplish.
I've seen something similar in an associates code. He leaves the previous non-functional code as a comment when he modifies it. So you end up with 80% of the code being junk that you have to try and wade through to find the real code.
Now, if the vendors would bring some truly modern AI technology to bare on the problem, I'm sure we could start seeing auto-generated comments that actually describe the algorithm that the code implements. All it needs is for the vendors to apply the same sort of resources to development tools as they throw at their Office Productivity suites.
I know it's common practice for some to fill their code with this sort of duplicated information, but I find it just makes it harder to see the logic of the code. It's like the standard Java doco pages. A bland listing of member functions and objects is useless without details of how it is used and what the functions actually accomplish.
I've seen something similar in an associates code. He leaves the previous non-functional code as a comment when he modifies it. So you end up with 80% of the code being junk that you have to try and wade through to find the real code.
Now, if the vendors would bring some truly modern AI technology to bare on the problem, I'm sure we could start seeing auto-generated comments that actually describe the algorithm that the code implements. All it needs is for the vendors to apply the same sort of resources to development tools as they throw at their Office Productivity suites.
Visual Studio will use the summary, param, returns, and remarks tags located at the top of a method/property/class to derive Intellisense when calling the code. So if you comment a method ???GetRecords??? you will see the comments as Intellisense when you type ???GetRecords(???
Are you talking about the comments that the product in this article create, or the ones Visual Studio creates automatically? I'm suspecting it's the later.
I'm referring to those added by the documentation tool described in this article and it's relatives rather than the IDE.
I'm referring to those added by the documentation tool described in this article and it's relatives rather than the IDE.
Good comments are produced by good developers, software tool is irrelevant.
This article describes a tool that automatically generates comments. The developer isn't writing them.
My question is where are the really clever tools that do more than pulling out the method signature and describing it in English. That is useless as far as I can see as your just duplicating information and cluttering up the code.
My question is where are the really clever tools that do more than pulling out the method signature and describing it in English. That is useless as far as I can see as your just duplicating information and cluttering up the code.
I don't consider this generating comments. It's basically structuring a comment ready to be filled in, and then marking it up so some other thingy can differentiate them from ordinary annotation.
In and of itself it's useless self defeating unmaintainable drivel, you need a good developer (better still a pair) to fill in the comments.
In and of itself it's useless self defeating unmaintainable drivel, you need a good developer (better still a pair) to fill in the comments.
Rather than waiting indefinitely for the features you've suggested to be implemented in GhostDoc, why not check out AtomineerUtils Pro Documentation, which already does everything GD does and much, much more (including documenting exceptions thrown within a method). It supports XML, JavaDoc, Qt and Doxygen comments, and works for C#, C++/CLI, C++, C, Java and Visual Basic. It can word wrap your comments and has many options to completely control the style and layout of the comment blocks.
For a feature comparison with GhostDoc and other add-ins, see:
http://www.atomineerutils.com/compare.php
For a feature comparison with GhostDoc and other add-ins, see:
http://www.atomineerutils.com/compare.php
Are there any real-world examples of the comments it creates? In other words real production code with significant complexity. The examples they give look a bit contrived.
Examples tend to look contrived because you want a few examples to show the range of results that are achieved.
You should not expect these tools to completely document your code for you, but they will significantly reduce the time and work that you need to put in to create excellent documentation.
Specifically, AtomineerUtils will:
1) Gather all available info it can from the code and summarise it in one place. This info is used in intellisense comments and external documentation, giving access to the docs in places where the source code is not available, or where it takes extra time and effort to find and read the source code to work out the details of how to use it. "Self documenting" code is a great start, but having the information instantly at your fingertips saves *so* *much* *time*. Using auto-complete on variable/type names doesn't write the code for you, it makes coding faster and easier. So why not use tools to write/update documentation fast as well?!
2) It tries hard to produce a human readable text description as a quality basis for your own documentation. With a stress on the word "basis" - you need to fill in those crucial extra details that other programmers need to understand to use/update your method correctly.
3) Where possible it re-uses documentation from base classes, overloads, properties and parameters elsewhere in your class.
4) It also constructs comments from a library of documentation, so well known cases are pre-defined and consistent.
5) It can add many useful things (optional entries for base classes/methods, author/date/time, etc)
6) It updates docs to ensure they are in sync with changes to the code
7) It ensures docs conform to a clear set of style guidelines
8) It applies word wrap, reformatting and controls whitespace to keep comments tidy and well formed, and can ensure the text is legal (e.g. converts characters like & into legal XML entities like & < >)
If you try to do some or all of the above, you'll spend a lot of time documenting. Let the tools automate as much as they can so you can concentrate on describe all the additional things that cant be implied from self documenting code (such as whether a parameter can be null, what the return code is for an error condition, etc.)
At the end of the day, there's a free trial - don't take my word for it, try it on your own code and see how well it does
You should not expect these tools to completely document your code for you, but they will significantly reduce the time and work that you need to put in to create excellent documentation.
Specifically, AtomineerUtils will:
1) Gather all available info it can from the code and summarise it in one place. This info is used in intellisense comments and external documentation, giving access to the docs in places where the source code is not available, or where it takes extra time and effort to find and read the source code to work out the details of how to use it. "Self documenting" code is a great start, but having the information instantly at your fingertips saves *so* *much* *time*. Using auto-complete on variable/type names doesn't write the code for you, it makes coding faster and easier. So why not use tools to write/update documentation fast as well?!
2) It tries hard to produce a human readable text description as a quality basis for your own documentation. With a stress on the word "basis" - you need to fill in those crucial extra details that other programmers need to understand to use/update your method correctly.
3) Where possible it re-uses documentation from base classes, overloads, properties and parameters elsewhere in your class.
4) It also constructs comments from a library of documentation, so well known cases are pre-defined and consistent.
5) It can add many useful things (optional entries for base classes/methods, author/date/time, etc)
6) It updates docs to ensure they are in sync with changes to the code
7) It ensures docs conform to a clear set of style guidelines
8) It applies word wrap, reformatting and controls whitespace to keep comments tidy and well formed, and can ensure the text is legal (e.g. converts characters like & into legal XML entities like & < >)
If you try to do some or all of the above, you'll spend a lot of time documenting. Let the tools automate as much as they can so you can concentrate on describe all the additional things that cant be implied from self documenting code (such as whether a parameter can be null, what the return code is for an error condition, etc.)
At the end of the day, there's a free trial - don't take my word for it, try it on your own code and see how well it does
... don't waste their time doing things that the computer can automate.
Do you use intellisense to auto-complete your variable/type names?
If so, what is different about using a tool to save you lots of time in documenting?
Of course the tool does not *do* the entire job for you, any more than intellisense will write the code for you. But it helps you do the job better and faster. You will always need to add information to complete the documentation, but these tools save you so much time getting started and keeping the code and docs in sync. (Typical users save $2000-$3000 worth of programmer minutes per year)
Do you use intellisense to auto-complete your variable/type names?
If so, what is different about using a tool to save you lots of time in documenting?
Of course the tool does not *do* the entire job for you, any more than intellisense will write the code for you. But it helps you do the job better and faster. You will always need to add information to complete the documentation, but these tools save you so much time getting started and keeping the code and docs in sync. (Typical users save $2000-$3000 worth of programmer minutes per year)
If the comments do nothing but clutter up the code and provide no more information than is already obvious from the code, it is a negative when it comes to reading code.
I just don't get the point of this sort of comments. When I inherit code, which is pretty common, I don't find these comments useful. On the contrary, they clutter up the code and make it more difficult to understand.
I just don't get the point of this sort of comments. When I inherit code, which is pretty common, I don't find these comments useful. On the contrary, they clutter up the code and make it more difficult to understand.
Visual Studio lets you collapse it, it doesn't clutter stuff up.
J.Ja
J.Ja
Expanded or not a useless comment just gets in the way.
The problem isn't really the tools they can save you a bit of typing and apply a format for the comment so you can extract simple documentation, but without developer discipline, they are a total waste of space.
Poor annotation is worse than no annotation. Always has been, always will be, and what these tools produce is poor, can't be anything else.
The tools don't bother me, people who present them as press this button you have documentation, drive me wild.
The problem isn't really the tools they can save you a bit of typing and apply a format for the comment so you can extract simple documentation, but without developer discipline, they are a total waste of space.
Poor annotation is worse than no annotation. Always has been, always will be, and what these tools produce is poor, can't be anything else.
The tools don't bother me, people who present them as press this button you have documentation, drive me wild.
1) This is not a magic fairy that does all your work for you, it is a tool for you to use to significantly speed up and improve the process of documenting code. It's a Resharper for docs rather than code. Do you complain that Resharper produces rubbish code? Or do you expect to have to do a little bit of the work yourself?
2) Without using a tool like this, programmers often let their comments get out of sync with the code, and *that* is when they become useless. The tool is therefore there to avoid "useless" comments.
3) A doc comment is a summary that brings together all the useful information from the code in a single place, in a standard and easy to read format. Why spend 2 minutes reading the code when you can read the summary in 10 seconds?
4) The programmer will augment the auto-generated documentation with all the critical info you need (can this parameter be null? Does index count from 0 or 1? what is returned to represent "not found"?). This information can often take a lot of reading of code to work out.
5) When you are calling a method, seeing intellisense pop up in a tooltip above your cursor is much faster than having to find the source code, read it, and then return. If you're not using intellisense, you're quite simply wasting a lot of time.
6) You won't always have easy access to the source code.
7) No, doc comments are not the basis of user documentation, unless your users are programmers and you are writing a library. Doc Comments are for describing how your code works to the programmers who have to maintain or call your code.
8) The act of writing doc comments makes you "describe your code to another person". Most people find that this process forces them to form a clear description of themethod, and thus gain a clear understanding of what they intend it to do. Just as unit tests make you think about the design, so do doc comments. The result is that you produce better quality, lower-defect code faster.
2) Without using a tool like this, programmers often let their comments get out of sync with the code, and *that* is when they become useless. The tool is therefore there to avoid "useless" comments.
3) A doc comment is a summary that brings together all the useful information from the code in a single place, in a standard and easy to read format. Why spend 2 minutes reading the code when you can read the summary in 10 seconds?
4) The programmer will augment the auto-generated documentation with all the critical info you need (can this parameter be null? Does index count from 0 or 1? what is returned to represent "not found"?). This information can often take a lot of reading of code to work out.
5) When you are calling a method, seeing intellisense pop up in a tooltip above your cursor is much faster than having to find the source code, read it, and then return. If you're not using intellisense, you're quite simply wasting a lot of time.
6) You won't always have easy access to the source code.
7) No, doc comments are not the basis of user documentation, unless your users are programmers and you are writing a library. Doc Comments are for describing how your code works to the programmers who have to maintain or call your code.
8) The act of writing doc comments makes you "describe your code to another person". Most people find that this process forces them to form a clear description of themethod, and thus gain a clear understanding of what they intend it to do. Just as unit tests make you think about the design, so do doc comments. The result is that you produce better quality, lower-defect code faster.
Totally and completely wrong!
The code is How.
Doc comments are What
Annotation is Why.
You've got the entire thing bass ackwards
The requirement is to show Customer A's Invoices
For that you need something that will return a list of invoices for customer.
You need a set of unit tests that will prove that you can get 0,1 or many of something called invoice for something called customer that doesn't miss any.
After that how is irrelevant is to what ever is calling the code. If it is then your code is crap, and no amounbt of dicumentation is ever going to make it better.
Documenting after will always fail in a commercial environment, because once the code is deemed good enough, the resources required to go through and document it will disppear before you've run up the tool to do it.
Developers let their comments get out synch, sheesh.
The code is How.
Doc comments are What
Annotation is Why.
You've got the entire thing bass ackwards
The requirement is to show Customer A's Invoices
For that you need something that will return a list of invoices for customer.
You need a set of unit tests that will prove that you can get 0,1 or many of something called invoice for something called customer that doesn't miss any.
After that how is irrelevant is to what ever is calling the code. If it is then your code is crap, and no amounbt of dicumentation is ever going to make it better.
Documenting after will always fail in a commercial environment, because once the code is deemed good enough, the resources required to go through and document it will disppear before you've run up the tool to do it.
Developers let their comments get out synch, sheesh.
1 - If the comments are of no value, which is what my position is, it doesn't matter how easy they are to maintain.
3 - Reading the code to determine the information these automatically generated comment include is significantly quicker and is always correct. A glance is enough to see the parameters, return type and the like. Or at least it is if you keep your code neat.
5 - Intellisense doesn't rely on these comments. It gets it's information directly from the code. I use it all the time. This is another reason the "structural" comments are of no value. If I want to see the list of members or the calling convention, Intellisense does that for me. Or an object browser.
3 - Reading the code to determine the information these automatically generated comment include is significantly quicker and is always correct. A glance is enough to see the parameters, return type and the like. Or at least it is if you keep your code neat.
5 - Intellisense doesn't rely on these comments. It gets it's information directly from the code. I use it all the time. This is another reason the "structural" comments are of no value. If I want to see the list of members or the calling convention, Intellisense does that for me. Or an object browser.
It's not about wasting time writing incorrect or useless rubbish. Of course that's of no use.
It's about making your code information rich and fast for a team to understand, use and maintain. Putting the crucial information in a doc comment significantly speeds up access to that information - a plot summary is always faster to read than the entire book (A parameter is sometimes easy to understand at a glance, but often you have to read an entire method quite carefully before you can work out what return values it will provide under what circumstances, or what exceptions it might throw. Or you may find it useful to follow a hyperlink to other relevant classes/methods that are not expressed in the code at all. Or you may just want to know quickly what the method is designed to achieve, not read carefully how it does it and then try to derive its intent from that. If you've never encountered these issues, then it's unlikely you've ever had to work in a team on a large/long-term project, working on complex code that you didn't personally write only a few days ago).
These tools significantly speed up the process of providing good docs so you can gain from their many benefits without the cost in time/effort of having to meticulously construct and maintain them.
It's about making your code information rich and fast for a team to understand, use and maintain. Putting the crucial information in a doc comment significantly speeds up access to that information - a plot summary is always faster to read than the entire book (A parameter is sometimes easy to understand at a glance, but often you have to read an entire method quite carefully before you can work out what return values it will provide under what circumstances, or what exceptions it might throw. Or you may find it useful to follow a hyperlink to other relevant classes/methods that are not expressed in the code at all. Or you may just want to know quickly what the method is designed to achieve, not read carefully how it does it and then try to derive its intent from that. If you've never encountered these issues, then it's unlikely you've ever had to work in a team on a large/long-term project, working on complex code that you didn't personally write only a few days ago).
These tools significantly speed up the process of providing good docs so you can gain from their many benefits without the cost in time/effort of having to meticulously construct and maintain them.
This discussion has been taken to The Water Cooler / View thread
The utterly failed model of represented code with monolithic text files.
Comments, in a superior system (OutSystem's Agile Platform, Alpha Software's Alpha Five, etc. etc. etc.) are META DATA both in use and in form, while in traditional, mainstream programming, comments are just text that is treated differently by the compiler and tools.
J.Ja
Comments, in a superior system (OutSystem's Agile Platform, Alpha Software's Alpha Five, etc. etc. etc.) are META DATA both in use and in form, while in traditional, mainstream programming, comments are just text that is treated differently by the compiler and tools.
J.Ja
The best the tool can do is name and signature.
int foo(int)
What use is that?
Comment : This function returns the square of the argument
Better? Why didn't they call it Squared. What uses is when after getting the wrong result and you find it returns the cube?
The tools, aid competent developers in competent environments, they don't substitute for one or both.
int foo(int)
What use is that?
Comment : This function returns the square of the argument
Better? Why didn't they call it Squared. What uses is when after getting the wrong result and you find it returns the cube?
The tools, aid competent developers in competent environments, they don't substitute for one or both.
They are complaining about comments littering the code. The answer is a metadata system where comments are appended to code.
J.Ja
J.Ja
even better if you could do some validation of meta data agaisnt code, flag them as out of sync etc. But as soon as you drop into unformatted english, we've still got the age old problem.
I still firmly believe while we are commenting code instead of implementing intent at best we always be holding the brown end of the stick.
Can't see the code for comments, is an issue I've run into many times, in every case the comments were useless, out of date, or just plain crap. I don't believe this is a coincidence.
I still firmly believe while we are commenting code instead of implementing intent at best we always be holding the brown end of the stick.
Can't see the code for comments, is an issue I've run into many times, in every case the comments were useless, out of date, or just plain crap. I don't believe this is a coincidence.
... is that they represent logic much more visually, and intent is MUCH easier to determine. Also, they allow metadata directly on the commands. For example, in Agile Platform, I drag a ForEach component on the screen, and when it lands on the screen, it says "ForEach" on it, but the title is highlighted with my cursor in it, for me to change it's name. That really encourages you to type "ForEach Invoice" or perhaps, just "Invoice" and let the symbol convey the "ForEach" aspect. When you see the logic laid out in a flowchart, intent is almost more clear. I'll put it this way... I've come back to extraordinarily complex pieces of logic months after I wrote them, and with under a minute's though, started making changes... in code that had zero "comments" as the system uses it. That's better than anything I ever got out of text-based comments, regardless of how in-sync or well written they were.
J.Ja
J.Ja
....
You are going to use doc comments as the basis for your user documentation?
Really?
You are going to use doc comments as the basis for your user documentation?
Really?
I happen to like well commented code. I like explicit header information. I have tried both Ghost Docs and the Atomineer product and like both, but I like Atomineer's product better; however, since my employer (at my last job where I used them) wouldn't pay for it, i settled on the free option provided by Ghost Doc.
It's been awhile since I've used them, but I thought they did help intellisense by providing documentation for your method parameters and return types (maybe that's just in my head?). If it does, who want's to use "go to definition" just to figure out what the exact purpose of each parameter is? Maybe you, but not me...
I work with people who have named parameters "p" or "_p", so the more information they are forced to provide through updated comments the better for someone who maintains their code...yes it's preferable to have self documenting code with expressive naming, but that's not always the case and when you inherit poorly written code, it is helpful to have slightly modified comments and the easier it is to produce these comments, the better the chance that they will actually be written.
I give it a +1.
It's been awhile since I've used them, but I thought they did help intellisense by providing documentation for your method parameters and return types (maybe that's just in my head?). If it does, who want's to use "go to definition" just to figure out what the exact purpose of each parameter is? Maybe you, but not me...
I work with people who have named parameters "p" or "_p", so the more information they are forced to provide through updated comments the better for someone who maintains their code...yes it's preferable to have self documenting code with expressive naming, but that's not always the case and when you inherit poorly written code, it is helpful to have slightly modified comments and the easier it is to produce these comments, the better the chance that they will actually be written.
I give it a +1.
- Keyboard Shortcuts:
- Prev
- Next
- Toggle
