🔒 Locked

Too much comments?

Started by Sand_Hawk Mar 3, 2003 at 10:26 AM 4 replies 200+ views

Original Post

Mar 3, 2003 at 10:26 AM

I just installed a line counter for VC++ 6 so I can see how much code/comments I have. I ran the thing and it turns out I have 37% comments in my code. See for yourself I ussually have above each function I write in my code something like this:

  
//////////////////////////////////////////////////////////////////////////////

// C I T E M D B :: D E L E T E I T E M

//

// Deletes an item from the database. Only delete an item from the DB if you

// are sure there it isn''t in use.

//

// Parameters: DWORD dwItemID - Item to delete

// Returns:    TRUE when successfully deleted, otherwise FALSE

//////////////////////////////////////////////////////////////////////////////

And ofcouse then I have the normal comments in my code. Do I write too much comments? Sand Hawk ----------------

(Inspired by Pouya)

JuNC

Mar 3, 2003 at 10:32 AM

No.

Unless you are commenting every line:



int aVar = 2;  // set aVar to 2

I don''t think it is possible to ''over comment''

However, if you do have redundant comments or confusing ones which don''t match the code, you could get into difficulties so it''s all a balance.

Zipster

Mar 3, 2003 at 11:27 AM

Sand_Hawk: Your demonstrated commenting style will be much appreciated by everyone who works with your code. If anything, it''s more proper than not.

flangazor

Mar 3, 2003 at 11:41 AM

I firmly believe IDE''s need a collapseable comment features. e.g. clicking a plus/minus box in the margin will expand/collapse the comment or function on that line. It would increase readability tremendously, imo.

civguy

Mar 3, 2003 at 12:00 PM

Isn't the first line a bit redundant in your comment? It's pretty obvious what's the function name if one looks at the following line where the actual definition is.. And now that it's all caps, it's impossible to say what's the real name of the function (is it DeleteItem or deleteItem?). The spacing makes it hard to read too.

I document everything with Doxygen style

    
/// Deletes an item from the database. Only delete an item from the DB if you

/// are sure there it isn't in use.

/// @param dwItemID Item to delete

/// @return TRUE when successfully deleted, otherwise FALSE

quote:
And ofcouse then I have the normal comments in my code.

What is normal? If you comment too much depends pretty much on how redundant the normal comments you make are.

[edited by - civguy on March 3, 2003 1:05:17 PM]

Topic Locked

This topic has been locked by a moderator. New replies are not allowed.