Programming Forums > Application Development > C++

ReggaetonKing · May 20th, 2006, 6:43 AM

Quote:

Originally Posted by grumpy

I generally seek to write code in a manner that avoids unnecessary comments. For example, picking names of variables/functions/types well can mean the code itself is its own documentation; comments are then less necessary.

I do the exact same thing!

DaWei · May 20th, 2006, 7:48 AM

Quote:

every function has to have pre and post conditions stated, what its intent is and how it is called. all variables are labeled and explained. any step that is not simple needs some form of explanation as to be easily understood when reading the comments.

I think you're mixing up design and coding.

Narue · May 20th, 2006, 7:58 AM

>And it makes it eaier to read.
Real programmers don't comment. If it was hard to write, it should be hard to read.

But seriously, I try to make my code self-documenting. That way the only comments I need are for exceptionally obtuse segments and documenting my intentions for pieces of code.

Ooble · May 20th, 2006, 1:05 PM

I comment when I remember. When I go back to code, I can never remember what it does. You have been warned!

Prm753 · May 20th, 2006, 5:03 PM

I always forget to comment when I need to. I hate going back to something and saying "Now what the crap does this do again?".

Harakim · May 21st, 2006, 1:50 PM

I think all IDES should come with an option to hide all comments, but not with those +/- signs. There should be an option that just plain hides them all. I comment because my school makes me, but a lot of the time the code is 100 times harder to read because the comments are everywhere. Other times, I really want to see the comments real quick. I rarely use comments for more than like 30 seconds.

DaWei · May 21st, 2006, 1:57 PM

An IDE is a tool. It can't reveal what's not there or add what isn't. The person maintaining your code might not have your same IDE or editor. There's a real world of code which is expensive to produce and expensive to maintain, despite the fact that it might not yet have bitten some as-yet unweaned novice in the butt. Comments are for those who follow; sometimes that is oneself, sometimes not.

Harakim · May 21st, 2006, 2:05 PM

I write comments.
I click the minus next to them in visual studio and they sort of go away

I would like to be able to do this with all of them simultaneously, except make them all go away. I'm 100 percent sure IDEs can do this since VS can remove comments.

Booooze · May 21st, 2006, 2:06 PM

I add some comments when in midst of creating something. Then, near the end, when I am going to add the last few things, and then head to Beta and debug, I go back and comment it all where needed. Sometimes my code is difficult, sometimes it is. I'm actually at this commenting process now. I find the hardest part is trying to figure out what actually to write. I know it's supposed to describe the function and explain what it does, but I always double guess myself and wonder if it's enough.

Jessehk · May 21st, 2006, 5:25 PM

I make a habit of documenting methods and classes. Tools like doxygen for C++, rdoc for Ruby, and the integrated documentation of Python make this pretty easy to do.

I will only document the inside of methods/functions if they're cryptic or need explaining.

View Poll Results: Do you comment your code?
All the time	17	29.31%
Sometimes	35	60.34%
Never	5	8.62%
Commenting?	1	1.72%
Voters: 58. You may not vote on this poll

May 20th, 2006, 7:58 AM	#13
Narue Professional Programmer Join Date: Sep 2005 Posts: 419 Rep Power: 3	>And it makes it eaier to read. Real programmers don't comment. If it was hard to write, it should be hard to read. But seriously, I try to make my code self-documenting. That way the only comments I need are for exceptionally obtuse segments and documenting my intentions for pieces of code. __________________ Even if the voices aren't real, they have some pretty good ideas.

May 20th, 2006, 1:05 PM	#14
Ooble I eat cake for breakfast. Join Date: Jul 2004 Location: In my box. Posts: 4,434 Rep Power: 9	I comment when I remember. When I go back to code, I can never remember what it does. You have been warned! __________________ Me :: You :: Them

May 20th, 2006, 5:03 PM	#15
Prm753 Professional Programmer Join Date: Oct 2005 Location: United States Posts: 447 Rep Power: 3	I always forget to comment when I need to. I hate going back to something and saying "Now what the crap does this do again?". __________________ The world's first athletic computer geek! The home of PrProgramsStudios How not to post a question: <-- Please don't reply

May 21st, 2006, 1:57 PM	#17
DaWei Resident Grouch Join Date: Jun 2005 Posts: 6,453 Rep Power: 10	An IDE is a tool. It can't reveal what's not there or add what isn't. The person maintaining your code might not have your same IDE or editor. There's a real world of code which is expensive to produce and expensive to maintain, despite the fact that it might not yet have bitten some as-yet unweaned novice in the butt. Comments are for those who follow; sometimes that is oneself, sometimes not. __________________ Abstraction doesn't make it impossible to write bad code; it makes it possible to write superior code. Contributor's Corner: Grumpy on C++ Exceptions DaWei on Pointers

May 21st, 2006, 1:50 PM	#16
Harakim Hobbyist Programmer Join Date: May 2006 Location: West Jordan, Utah, United States Posts: 176 Rep Power: 3	I think all IDES should come with an option to hide all comments, but not with those +/- signs. There should be an option that just plain hides them all. I comment because my school makes me, but a lot of the time the code is 100 times harder to read because the comments are everywhere. Other times, I really want to see the comments real quick. I rarely use comments for more than like 30 seconds.

May 21st, 2006, 2:05 PM	#18
Harakim Hobbyist Programmer Join Date: May 2006 Location: West Jordan, Utah, United States Posts: 176 Rep Power: 3	I write comments. I click the minus next to them in visual studio and they sort of go away I would like to be able to do this with all of them simultaneously, except make them all go away. I'm 100 percent sure IDEs can do this since VS can remove comments.

May 21st, 2006, 2:06 PM	#19
Booooze Expert Programmer Join Date: Mar 2006 Location: Igloo Posts: 710 Rep Power: 3	I add some comments when in midst of creating something. Then, near the end, when I am going to add the last few things, and then head to Beta and debug, I go back and comment it all where needed. Sometimes my code is difficult, sometimes it is. I'm actually at this commenting process now. I find the hardest part is trying to figure out what actually to write. I know it's supposed to describe the function and explain what it does, but I always double guess myself and wonder if it's enough.

May 21st, 2006, 5:25 PM	#20
Jessehk The Oblivious One Join Date: May 2005 Location: Ontario, Canada Posts: 641 Rep Power: 4	I make a habit of documenting methods and classes. Tools like doxygen for C++, rdoc for Ruby, and the integrated documentation of Python make this pretty easy to do. I will only document the inside of methods/functions if they're cryptic or need explaining. __________________ Dr. Zoidberg: [ecstatic] I'm going to a movie... with FRIENDS!

Currently Active Users Viewing This Thread: 1 (0 members and 1 guests)

Thread Tools
Show Printable Version Email this Page
Display Modes
Linear Mode Switch to Hybrid Mode Switch to Threaded Mode

Programming Forums > Application Development > C++

Commenting your code