Archived

This topic is now archived and is closed to further replies.

Sand_Hawk

Too much comments?

Recommended Posts

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)

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites
Guest Anonymous Poster
How you design your function comments, is a matter of taste.

But try to write self explanatory code.

Share this post


Link to post
Share on other sites
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.

Share this post


Link to post
Share on other sites
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]

Share this post


Link to post
Share on other sites