PDA

View Full Version : Do you comment?



HJvK
12-27-2005, 09:59 AM
When you are coding programms... do you use comments?

PING
12-27-2005, 10:08 AM
Yes, of course, i comment my programs..That makes them readable not only for others but also for me when i see them after a gap of some months or so.

Govtcheez
12-27-2005, 10:08 AM
If you don't comment, you're either lazy or an idiot. Probably both.

ElastoManiac
12-27-2005, 10:09 AM
I comment only extreme stuff, that isn't recognizable at first look.

HJvK
12-27-2005, 10:16 AM
Well, mostly I comment but I understand my last scipt totaly now, so right now I am to lazy to comment.

adrianxw
12-27-2005, 10:24 AM
>>> but I understand my last scipt totaly now,

Will you when you suddenly and urgently need to modify it in 6 months time?

Of course I comment, only fools do not.

PJYelton
12-27-2005, 10:40 AM
I don't comment, I enjoy the hours of painfully looking at my code trying to figure out my logic from months ago.

ElastoManiac
12-27-2005, 11:12 AM
I don't comment, I enjoy the hours of painfully looking at my code trying to figure out my logic from months ago.
i do too.

7smurfs
12-27-2005, 11:20 AM
Yes.

valis
12-27-2005, 02:31 PM
Even when something makes sense, if it's old or not your code then your going to have to spend some time figuring out what is happening, how long that takes depends on how well you name stuff and how complex your problem is/was.

I always comment my code, even the obvious stuff, it really doesn't slow down or hinder my abilities.

ElastoManiac
12-27-2005, 02:56 PM
when naming stuff properly and creating classes, there is no much need for commenting...
but it's fun anyway

Slacker
12-27-2005, 03:22 PM
Comments are for weenies. ;)

ElastoManiac
12-27-2005, 03:23 PM
what a stupid thread...

Dae
12-28-2005, 02:22 AM
Of course.

I've always done concept commenting. I'm trying to get into documentation commenting. Thats where you explain the purpose, results, and such of a function, class, and such. Its very useful so you can use javadoc to make a document out of it, and because in real programs people (and yourself in 6 months) need to know the concepts behind your program functions. If it takes you a week to come up with a framework of classes for a game, you aren't going to just leave it and not comment the concept you resulted with are you? After all it did take you a week to come up with.. Theres plenty of reasons of why commenting is good, but none on why they are bad, so just write them out when you're thinking about what to do next in your program.

HJvK
12-28-2005, 02:25 AM
>>> but I understand my last scipt totaly now,

Will you when you suddenly and urgently need to modify it in 6 months time?

Of course I comment, only fools do not.
Well, my script isn't that difficult yet!
I am to noob to make a difficult script right now.
BTW: I used php, I learned putting comments in my script because else I was looking hours to figure out what has gone wrong.
I enjoyed it, yes! But it just took me to long... Sometimes I had only about an hour and still it wasn't finished, the next morning I forgot where I was... :eek:
So I had to start over again

Slacker
12-28-2005, 06:13 AM
>Well, my script isn't that difficult yet!
It doesn't have to be difficult. You might look at it later and wonder what you were thinking, why you picked that particular solution. Good comments rarely describe the mechanism and more often hint to the reasoning behind the design. It's much more useful to have a look into the programmer's brain than a play by play of what each line of code does. The latter can be figured out fairly easily, but the former is lost when the original programmer can't be found or has forgotten.

TactX
12-28-2005, 06:19 AM
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

Jaqui
12-28-2005, 07:46 AM
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.

alphaoide
12-28-2005, 12:03 PM
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.

ElastoManiac
12-28-2005, 12:42 PM
This thread is so pointless. I'm sure 99% people would say you should comment. If i was moderator i would lock it.

adrianxw
12-28-2005, 03:16 PM
>>> 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.

Dae
12-28-2005, 03:20 PM
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.

VirtualAce
12-28-2005, 04:12 PM
Yes I do comment. No I'm not really good at knowing when to comment and when not to. Over-commenting makes the code look rather hideous and under-commenting causes it to be nearly unreadable and hard, if not impossible, to follow.

I comment, but probably not as much as I need to. Perhaps if I actually coded in a dev team with some knowledge about them I would learn to comment much better.

Jeremy G
12-28-2005, 06:58 PM
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.

h_howee
12-28-2005, 11:17 PM
Only if Theres lots of code. Even if i comment it, after a month or so i won't understand the comments either :D

nvoigt
12-29-2005, 04:55 AM
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.

cboard_member
12-29-2005, 01:25 PM
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



/* <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



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).