Code usability - CodeProject

Download source files - 3 Kb

This VB procedure helps any developer to easily add comments to his/her code. The comments including some function details like function name, input parameter and return value. Also, the date when the function was written and the author name. All are retrieived automatically and it saves the developer time.

How does it work?

The developer marks the function she wants to remark.
The code parses the selected text and gets all of the relevant data from the function (i.e. name,input and return value)
The description should be filled by the author
Date is written as the current date
Author is taken by the Windows login name

How can you use it?

- Open VC
- Go to Tools->Customize->Commands->Macros
- On the right pane click on the function AddFunctionDescription (should be the 1'st one), then drag it to the toolbar.
- You should see this function in the toolbar
- Go to Tools->Macors->Macro explorer
- In the tree, open Samples->DevStudio6Editor
- Right Click on AddFunctionDescription and choose Edit
- Replace the current code of this procedure with the one you have in the attached zip file.
- Save all the changes in all of the IDEs
- Select any function you have in the code (select the whole row)
- Click on the AddFunctionDescription button in the toolbar
- You will see the proper remark
- Sample: Supposed that you have the function void Foo(int bar) written by a guy
- named Henry. This macro will add the next lines just below you selected
- function.
- // ********************************************************************
- // Function name : Foo
- // Description :
- // Return type : void
- // Argument : bar
- //
- // Date : 1:10PM 12/13/2002
- // Author : henry
- // ********************************************************************

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

About the Author

oferudi

Israel

Member

Article Top

Poor

Excellent

Add a reason or comment to your vote: x
Votes of 3 or less require a comment

Comments and Discussions

You must Sign In to use this message board. (secure sign-in)

Search this forum
	Profile popups Noise Layout Per page

It doesn't work

MikeTheProgrammer

1:36 21 Sep '03

I tried to insert the current code into the specified sample macro but I got the following error: "Line 3 expected end of statement: Dim Header, prms As String". . Also I don't understand why you don't use .DSM file instead of overwriting the SAMPLE Macro. Michael MikeTheProgrammer
Sign In·View Thread·Permalink

C#.NET already has automatic comment ability...

Marc Clifton

1:14 17 Dec '02

by typing "///" above a method, generating XML fields which can be extracted by free tools (like NDoc http://ndoc.sourceforge.net/[^] )to generate very nicely formatted help.

Something VB.NET doesn't support.

Marc

Help! I'm an AI running around in someone's f*cked up universe simulator.
Sensitivity and ethnic diversity means celebrating difference, not hiding from it. - Christian Graus
Every line of code is a liability - Taka Muraoka

Re: C#.NET already has automatic comment ability...

Michael P Butler

0:04 19 Dec '02

I love that feature, about the only thing I miss when I go back to doing C++ code in VC6. Michael Fat bottomed girls You make the rockin' world go round -- Queen
Sign In·View Thread·Permalink

Re: C#.NET already has automatic comment ability...

Lennybacon

10:09 23 Dec '02

>> Something VB.NET doesn't support.

Just no, o.k. nothing build-in. I´ve seen someting for vb.net on http://vbxmldoc.tor-erik.net/

But i havent used it cause i only do it in c#.

Daniel

# THIS CODE AND INFORMATION ARE PROVIDED
# "AS IS" WITHOUT WARRANTY OF ANY
# KIND, EITHER EXPRESSED OR IMPLIED,
# INCLUDING BUT NOT LIMITED TO THE
# IMPLIED WARRANTIES OF MERCHANTABILITY
# AND/OR FITNESS FOR A PARTICULAR PURPOSE.

Re: C#.NET already has automatic comment ability...

Hades5k

7:29 20 Sep '07

Have you tried " ''' " above a method in VB.NET? -= HaDeS5k =- Christopher
Sign In·View Thread·Permalink

A revision history might be useful

Marc Clifton

0:57 17 Dec '02

I vaguely remember this article. Did you add the example? BTW, do C/C#/C++ style comments now work in VB? Marc Help! I'm an AI running around in someone's f*cked up universe simulator. Sensitivity and ethnic diversity means celebrating difference, not hiding from it. - Christian Graus Every line of code is a liability - Taka Muraoka
Sign In·View Thread·Permalink

Where is a StripTabs?

_Samael_

1:39 16 Dec '02


Sign In·View Thread·Permalink	1.00/5 (1 vote)

suggestions

Henry Jacobs

7:41 13 Dec '02

I agree with others that the article needs some improvement. However, I will offer constructive criticism.

I think an example of the input and output would help to avoid abrupt conclusions about the worth of this article. I have not tried the macro yet (I'm at work) but I looked at the code, it generates C++ comments using a VB macro.

VB is not my native language but the output is something like this (based on the code void Foo(int bar)):

//  ********************************************************************
//  Function name   : Foo
//  Description     : 
//  Return type     : void
//  Argument        : bar
//
//  Date            : 1:10PM 12/13/2002
//  Author          : henry
//  ********************************************************************

I suggest moving this article to “Macros and Add-ins.” Also, a more descriptive title would help others to locate it better (e.g. “Generate a Function Comment Header from the Function Definition”).

Re: suggestions

oferudi

19:42 16 Dec '02

I'm sorry guys.
Perhaps the article should be rephrased better.
Yet, I believe that it can help any VC++ developer (VC++ NET environment) in a way that she never needs to add any comments to the function.

To make things clear, Henry did right by using this sample, so please have a look what he got.
Based on the C++ function he wrote which is
void Foo(int bar)

He has now, this comments above his function header:
// ********************************************************************
// Function name : Foo
// Description :
// Return type : void
// Argument : bar
//
// Date : 1:10PM 12/13/2002
// Author : henry
// ********************************************************************

Isn't it great?

oferudi

Re: suggestions

jhwurmbach

21:39 16 Dec '02

First, let me say that (after the rewrite), you did a good job for an article, and I (having myself not posted any article yet) appreciate your support of this site.
But:
oferudi wrote:
Isn't it great?

Well, it might be help if you are obliged (e.g. by company policy) to document every function that way.
But it will not help in writing a description that is not in the header, nor does it add meaningful descriptions to the parameter. (How could it? No one would have expected this.)
But this is the hard part with documenting: Getting the meaning of your code transported, the reasons for your algorithm choice, the limitations the algorithm has and the constraints on the parameter values.

So, I think that this macro will have a bad effect on the documenting style of many user (a least on me it would have): With running the macro one thinks: "Well, now I have made a documentation for it, so this one is finished."
But it is not! The real job has just started.

--
"My opinions may have changed, but not the fact that I am right."
Found in the sig of Herbert Kaminski

Not being picky

Norm Almond

21:11 12 Dec '02

But to add a comment in VB, don't you just type ' ? <SARCASM> BTW your article rocks my world and is far too advanced for this site! </SARCASM>
Sign In·View Thread·Permalink

Re: Not being picky

David Stone

7:56 14 Dec '02

Yes. In fact, it's so advanced, it should really go here[^] I don't know whether it's just the light but I swear the database server gives me dirty looks everytime I wander past. -Chris Maunder Microsoft has reinvented the wheel, this time they made it round. -Peterchen on VS.NET
Sign In·View Thread·Permalink

Please reformat the text of your article

Matthias Mann

2:29 12 Dec '02

Hi, can you do it please, because it's not very good to read. And include a sample of what your function does. Ciao Matthias
Sign In·View Thread·Permalink

Re: Please reformat the text of your article leppie 8:10 12 Dec '02

...and pictures, we like pictures WebBoxes - Yet another collapsable control, but it relies on a "graphics server" for dynamic pretty rounded corners, cool arrows and unlimited font support.
Sign In·View Thread·Permalink

Re: Please reformat the text of your article

Uwe Keim

20:08 12 Dec '02

Would you trust in someone telling you something about "code usability" who even cannt format his own article?

That would be like Jakob Nielsen [^] doing his whole website with Flash...

--
- Free Windows-based Web Content Management System: http://www.zeta-software.de/enu/producer/freeware/download.html
- Scanned MSDN Mag ad with YOUR name: www.magerquark.de/misc/CodeProject.html
- See me: www.magerquark.de

Re: Please reformat the text of your article

Norm Almond

21:13 12 Dec '02

Uwe Keim wrote: Would you trust in someone telling you something about "code usability" who even cannt format his own article? LOL
Sign In·View Thread·Permalink