Where are the comments?

[RichAlgeni]

I'm going to smack some of you on the knuckles with a ruler in this post. Take a look at the code recently posted, especially when it comes to networking code in Features and Requests. Does anyone notice a glaring issue? It's the lack of comments in the code!

Part of being a productive coder is the ability to have someone else pick up your code, and be able work with it. No one here is perfect, we all make mistakes. Sooner or later, for whatever reason, someone may need to work with your code. It may even be you years down the road. Make it easier on them, and yourself. Document your code with comments explaining what the code is doing. You don't need to go crazy, just a few sentences here and there could make a big difference!

Also, use meaningful variables! Often they are self documenting, and will save you time in the long run!

Rich

[rsts]

While I can appreciate the value of well commented code, I would hate to discourage the posting of code which is uncommented.

This is a programmer's forum. We don't have to undertake a long term maintenance process. Figuring it out on your own can be a valuable part of the learning process. I would hate for people to feel there's some sort of standard they must achieve in order to post code.

Uncommented code here, is better than no code at all. Keep it coming.

[Shield]

What rsts said.

Anybody asking for help here should be glad to receive it in any form.
The code which is provided has to be written by someone and usually that someone
has other things going on than just being a helpful person.

Usually snippets posted here are rather short (with some exceptions of course)
and can be understood without too much commenting.

As rsts said, it's better to receive undocumented code than none.
And if anything is unclear the OP can just ask again to clarify.

[netmaestro]

Code: Select all

OpenWindow(0,0,0,320,240,"") ; Here I'm opening a window
ButtonGadget(0,10,10,100,20,"Button") ; I put a button on it
; wait a second, I have to fart... ok. Continuing.
Repeat ; Starting a loop
  Event = WaitWindowEvent() ; I need to know the events
Until Event=#PB_Event_CloseWindow ; After this event we don't need the window anymore
; My tummy feels better now

Just kidding, please don't take offense! You do raise a valid point, heard and understood.

[RichAlgeni]

I don't get mad, I just get even! Cue the evil laughter.....

You don't need to go crazy, just a few sentences here and there could make a big difference!

[LuCiFeR[SD]]

I don't get mad, I just get even! Cue the evil laughter.....

You don't need to go crazy, just a few sentences here and there could make a big difference!

Your evil laughter is girls evil laughter

[RichAlgeni]

Your evil laughter is girls evil laughter

I can't help it, Been married for 20 years and we have 17 year old twin girls...

It's the best I can do!

[idle]

I can't help it, Been married for 20 years and we have 17 year old twin girls...

If only you could get your wife and twins to subtitle what they're on about you might
be on to something!

[LuCiFeR[SD]]

I can't help it, Been married for 20 years and we have 17 year old twin girls...

It's the best I can do!

Did I say girls evil laughter was a bad thing... well it is bad, but a good kinda bad

& LOL @ idle

[RichAlgeni]

If only you could get your wife and twins to subtitle what they're on about you might
be on to something!

As if that would happen!

well it is bad, but a good kinda bad

They're bad!!!

[MachineCode]

There are only two valid reasons to comment code: (1) To explain something that isn't obvious, and (2) To explain why something was done. That's it. These two reasons cover everything in coding.

[jassing]

There are only two valid reasons to comment code: (1) To explain something that isn't obvious, and (2) To explain why something was done. That's it. These two reasons cover everything in coding.

And if you use meaningful variable & procedure names, and code clearly -- code can be "self commenting" -- I once had a project (years ago) where the boss said "Comment more" -- well we all kind of revolted and did things like this:

Code: Select all

; start the source code.
; open the console 
OpenConsole()
; assign the program's exe to a variable called "cProgramExecutable" of type string:
cProgramExecutable.s = ProgramFilename()
; Now we want to print that program file name out, and end the line with a new line:
PrintN(cProgramExecutable)
; If the program is on drive C:, we want to print "Happy Day" w/o a new line:
;   we will convert the string to upper case to compare the strings
If UCase(Left(cProgramExecutable,2))="C:"
	Print("Happy Day") ; Remember, we do not want to print a new line just yet.
Else ; If the drive is not C:, then print "Hello World" w/o a new line:
	Print("Hello World") ; Remember, we do not want to print a new line just yet.
EndIf ; We want to end our if/else control block.
; Now we are on a line with some text, let's print a couple of exclimation marks and add a new line:
PrintN("!!") ; Remember, we wanted to print 2 exlamation marks and print a new line
; we are now done, so let's close the console
CloseConsole()
; now that we have closd the console, we can end the program:
End; We have ended the program.
; this is the end of source code

We all thought the boss would come and say "Ok; you made your point" -- but no, he printed out and said "This is exactly what he wanted from now on"

this only made the coders that were consultants, they got to pad their stats "I wrote 15,000 lines of code today" -- since they just looked at "lines changed"; which usually included 4 lines of comments for one statement.

Comments can go overboard and actually make reading / updating code more difficult.
There is a balance; but if the code is well written, and in response to a specific question "How do I read the registry?" then comments are not required, since the code is in response to a question... a comment of "; Read the registry now" would be silly.

[Zach]

I agree that there is a balance.

Sometimes the situation calls for a clear explanation of what just happened. Other times it doesn't, because it is obvious.. i.e "2 + 2" or whatever.

But it is the many cases inbetween that are where comments are needed.

It's all fine and good to say, well you should be lucky to get help at all or we don't need to comment things that are "obvious". But who defines what is obvious?

Something might be obvious to a 20 year veteran, who knows a particular system or algorithm they are working with. But where does that leave someone like me?

Sometimes a lack of comments says "I couldn't be bothered to make the effort". To which I say, if you can't make the effort, I don't want your help anyway (needing a help file for the help file is an oxymoron, no?)

I view it as a matter of principle, and work ethic and standards. I don't code frequently so they help me a lot, and I also write them so they will help others.
The few people that have seen project files from me have complemented my commenting and structure. As a novice, I take great pride in that.

As veterans, the more experienced programmers should too.

Just try to remember, that code snippet you posted last week may be the first time someone has had to work with that particular API / Data Structure / Logical Problem. Comments are always useful to someone, somewhere.

[Tenaja]

Zach, don't throw the baby out with the bathwater. Even code lacking comments can be helpful to a newbie if you keep one finger on the f1 key...

[Zach]

Maybe I oversimplified my point. If uncommented code was the only resource I had, then of course I would make an effort to understand it.

I'm simply saying I don't have to like it, and that's not how it should be.