Post Reply 
 
Thread Rating:
  • 0 Votes - 0 Average
  • 1
  • 2
  • 3
  • 4
  • 5
Do you comment your code?
Jake Offline
Member
***

Posts: 184
Joined: Mar 2005
Post: #1
Do you comment your code?
Im just curious to see what % of you comment your code, I personally dont comment to much except when coding for someone else
2003.04.19 05:41 PM
Find all posts by this user Quote this message in a reply
macboy
Unregistered

 
Post: #2
Do you comment your code?
I picked sometimes because I comment important variables and subroutine groups in my code... not much else.
2003.04.19 05:45 PM
Quote this message in a reply
DoG Offline
Moderator
*****

Posts: 400
Joined: Mar 2005
Post: #3
Do you comment your code?
I try to put headerDoc style docs into the header files to discribe most functions and classes, but the critical ones at least.

I occasionally comment code in the implementation, but I am also writing documentation seperately at the same time. It is much easier to understand a typeset algorithm than trying to figure it out from the code.

I would say (way) less than half of my code is documented, in one way or the other, but the documentation does evolve with the code.

I don't see a point to commenting every single instruction, but well placed comments are helpful.

Also, there is not much point to documenting stuff that has already been documented in abundance or should be obvious. Using long variable names instead of cryptic abbreviations makes a lot of commenting obsolete.

And, with overloading C++ operators, a lot of code becomes much clearer. I found myself converting plain C code from tutorials, and cleaning it up so much in the process I was able to discard 90% of the comments with a clear consciousness.

DON'T PANIC
2003.04.19 06:04 PM
Visit this user's website Find all posts by this user Quote this message in a reply
OneSadCookie Offline
Genius Bar
*****

Posts: 2,154
Joined: Feb 2005
Post: #4
Do you comment your code?
Never. If it needs commenting, then either your function/variable names are too short, or the function itself is too long.

That said, I have used comments a couple of times recently. One of them was in a C++ class' destructor where it wasn't safe to delete one of the fields; the other was an error case in a constructor where I would usually have logged a message, but it wasn't safe to to so because the log hadn't been constructed yet.
2003.04.19 06:21 PM
Visit this user's website Find all posts by this user Quote this message in a reply
Josh Offline
Senior Member
****

Posts: 266
Joined: Mar 2005
Post: #5
Do you comment your code?
Quote:Originally posted by OneSadCookie
Never. If it needs commenting, then either your function/variable names are too short, or the function itself is too long.
Not all comments are because of function names or variable names. I comment extensively simply because it is easier to read a comment in most situations than the code. I know you will say "then the problem is your code" but I think most would say they can read english (or their native language) faster than their code. Tongue

On the other hand, there is no need to comment simple operations or function calls like printf but in general I comment a lot.
2003.04.19 06:43 PM
Find all posts by this user Quote this message in a reply
Joseph Duchesne
Unregistered

 
Post: #6
Do you comment your code?
I comment every routine sub and subsub(is that a term) in this format

'===== Main Player Movement ====='
'-=-=- Move Up -=-=-'
'-----little tiny thing-----'
'<- Inportant variable
'something I might need to know

(" ' " is the metal "//")
2003.04.19 06:49 PM
Quote this message in a reply
macboy
Unregistered

 
Post: #7
Do you comment your code?
Quote:Originally posted by Joseph Duchesne
I comment every routine sub and subsub(is that a term) in this format

'===== Main Player Movement ====='
'-=-=- Move Up -=-=-'
'-----little tiny thing-----'
'<- Inportant variable
'something I might need to know

(" ' " is the metal "//")
I do it like this:

' =--= Subroutine Group =--=
' =-= Smaller Group =-=
' Variable or note
2003.04.19 06:52 PM
Quote this message in a reply
Najdorf
Unregistered

 
Post: #8
Do you comment your code?
If I use well organized functions I don' t need it; most of the code I have written for games is now easy for me . But I understand that for code that is still difficult for me needs commenting.
2003.04.19 07:37 PM
Quote this message in a reply
NCarter Offline
Moderator
*****

Posts: 270
Joined: Feb 2005
Post: #9
Do you comment your code?
My code's pretty easy to read (so says my professional programmer friend), but if I don't comment everything clearly I forget what it all means after a couple of weeks. I don't comment every last instruction but I put in notes here and there to highlight different blocks of code so it's easier to skim.

Neil Carter
Nether - Mac games and comic art
2003.04.19 08:16 PM
Visit this user's website Find all posts by this user Quote this message in a reply
Mark Levin
Unregistered

 
Post: #10
Do you comment your code?
I comment headers, and any part of the implementation that's given me trouble or confusing me at the moment (where the code is in constant flux from having parts enabled and disabled as I narrow down the problem and try different solutions). To me, headers are the place for all the explanations of what a function does, there's not much for comments to get in the way of or interfere with the flow of, since a variable declaration or function prototype is pretty self-contained.

I agree that it's stupid to have comments like
Code:
velocity = 5;     //Set velocity to 5
, but a good comment can still say much more than any feasible name for a variable (nor do you want to have to call something like [mapLoader prepareArchivedObjectPlaceholderForReferenceLinkingStage] too many times).
2003.04.19 08:34 PM
Quote this message in a reply
Post Reply 




User(s) browsing this thread: 2 Guest(s)