Thread: Do you comment?

Originally Posted by PJYelton

I don't comment, I enjoy the hours of painfully looking at my code trying to figure out my logic from months ago.

"Weeks of coding can save you hours of planning." :P

Every programmer actually working will be required by the employer to comment.
so you might as well develop the habit.
lord knows that every company I've ever talked with has always REQUIRED properly commented code, and they each define properly commented for themselves.

if you do not comment code, then you do not have a job.

About going back to old code, don't you find class diagram, activity diagram and the like to be useful? If you the original coder, you may know where to find stuff in your code, but for others, do they need to go to source code level to find that this class import that class, this class is derived that class, etc?

To my (non-professional) experience, I need such higher level documentation more than commenting, especially when most lines of code is self-explanatory/trivial.

This thread is so pointless. I'm sure 99% people would say you should comment. If i was moderator i would lock it.

>>> If i was moderator i would lock it.

The thread illustrates some of the reasons why you should comment. Some of these may not be apparent to all members. Yes, 99% of people will comment, but stating the reasons is reason enough to keep the thread.

Originally Posted by ElastoManiac

This thread is so pointless. I'm sure 99% people would say you should comment. If i was moderator i would lock it.

If I was the moderator I would warn you for pointless posts (sometimes called spam). For example, 3/4 of your posts in this thread. I'm not sure if its from boredom.. but I hear programming is a good hobby.

>> but I understand my last scipt totaly now,

Most people do. I completely understand how my program with a bit less than 1000 lines does because it hasn't been a month since I wrote it. When I go back and look at that in 6 months I will have to read a lot of lines of code to understand whats going on again, or I can skip through the commenting to speed up the process. Since I'm the original programmer that could possibly trigger memory of the concept too (which is faster than reading all the code to get an idea). On that note it also varifies the reader has the same idea as the writer. As for other readers its much more helpful because they might not be used to your style of coding, might only need to reuse your code so they just need to know the idea behind it, and of course it helps in many other ways of understanding.

>> Well, my script isn't that difficult yet!

I'd say comment a little, but then I wouldn't have followed my own advice. When I was learning to program I barely commented as most of my scripts were less than 50 lines becuase I was just learning and testing. If you're making a game I would say don't worry too much about commenting, as usually people new to programming make some really basic games with way too many lines - like the ones with 500 lines, where only 25 arent cout/cin, switch/if statements, global variables, and pointless/misuse of classes.

I never comment my code.
I simply open a source file, use the scroll wheel to skim the entire file and I instantly understand the code part, and the programs entirety even if it's coded in multiple files.


I'm that amazing.

Well, mostly I comment but I understand my last scipt totaly now, so right now I am to lazy to comment.

So you wait with commenting until the point where even you don't understand your code anymore ? Just asking because that seems to be my colleagues method.

I fully understand my code now. It would be pretty sad if I didn't. Anyone else ( including me in 2 months time ) will not have worked with it the last weeks and will have no clue how it works. There can never be too much comment. If someone comes along and can understand it better without any comment, he can delete it to understand the code.

Good commenting is required by our coding standards at work ( which I wrote ). If you don't keep to the standard, you don't get bonus payments for on-time projects and have to fix it. Sadly, almost every project is considered "urgent" and so the first thing that gets skipped is a proper concept and planning stage and coding standards follow right behind. I think if every single project is considered "urgent" by upper management, upper management has no sense of planning and scheduling itself... but that's a WTF on it's own and not part of this topic.

No matter how much typing it involves I write a comment header for every function (unless vividly obvious), nothing special, just something along the lines of

Code:

/* <func_name>
 *     <purpose>
 * Returns: <values>
 */

If it's something that doesn't need commenting then I just put "// <func_name>" in case I need to find it later.

Of course it also depends what language you're programming in. I comment almost every line in assembly programs (usually not mov instructions unless they're a bit vague). I don't go over-board however, like

Code:

mov eax, ebx  ; load eax with ebx
add eax, ecx   ; add ecx to eax
cmp eax, 0xa  ; compare with 10h
jz     arse        ; jump to arse if zero
; etc

Then there's that whole argument over what is bad and good commenting over issues in the asm code above, but we could create a whole new thread for that (please don't).