Do you comment your code?

Ye' old general discussion board. Basically, for everything that isn't covered elsewhere. Come here to shoot the breeze, shoot your mouth off, or whatever suits your fancy.
This forum is not for asking programming related questions.

Moderator: General Moderators

Do you comment your code?

Always
11
38%
Usually
7
24%
Occasionally
10
34%
Never
1
3%
 
Total votes: 29

User avatar
Luke
The Ninja Space Mod
Posts: 6424
Joined: Fri Aug 05, 2005 1:53 pm
Location: Paradise, CA

Do you comment your code?

Post by Luke »

I must say I never have done it. For me, it makes the code unreadable while I'm writing it, although when I come back to it later on the rare occasion that I do comment it, it helps a LOT. I just never got into the habbit.
alvinphp
Forum Contributor
Posts: 380
Joined: Wed Sep 21, 2005 11:47 am

Post by alvinphp »

May all the people that don't ever comment get coal in your shoes for christmas.

Not only do I comment throughout a page, I have a description on the top of every method that I write before I code. I then use this as checklist to make sure I did everything I needed in the method.
Last edited by alvinphp on Thu Nov 10, 2005 1:35 pm, edited 1 time in total.
foobar
Forum Regular
Posts: 613
Joined: Wed Sep 28, 2005 10:08 am

Post by foobar »

No comments => uber n00b
User avatar
Luke
The Ninja Space Mod
Posts: 6424
Joined: Fri Aug 05, 2005 1:53 pm
Location: Paradise, CA

Post by Luke »

Yes... I suppose when I start working with other people it's going to be really irritating for them. I'm trying to get into the swing of doing it...
User avatar
Chris Corbyn
Breakbeat Nuttzer
Posts: 13098
Joined: Wed Mar 24, 2004 7:57 am
Location: Melbourne, Australia

Post by Chris Corbyn »

My $2....

Comments make your code much more sellable and far easier for others to pick up and change/use. They also make stopping/starting a project much easier.

I believe you should add descriptive comments but not all over the place. Why not everywhere? Because if you write your code correctly it should just "read" well to the point that the code tells you what it's doing, without having to follow comments around. Name your functions descriptively, name your variables in the same way, try to lay your code out in a logical pattern.

If you combine *good* descriptive comments with well laid out, easy to read code you'll make it easier for yourself and others to use :D
McGruff
DevNet Master
Posts: 2893
Joined: Thu Jan 30, 2003 8:26 pm
Location: Glasgow, Scotland

Post by McGruff »

I'd agree with d11wtq that good naming can reduce the need for comments. Unit testing also helps: the tests act as a source of documentation. Although comments can get out of sync with code, the tests never lie. Comments have to be maintained which is extra work. All I like to do is give a brief description of a class and describe parameters and return values for the public methods only.
redmonkey
Forum Regular
Posts: 836
Joined: Thu Dec 18, 2003 3:58 pm

Post by redmonkey »

McGruff wrote:I'd agree with d11wtq that good naming can reduce the need for comments. Unit testing also helps: the tests act as a source of documentation. Although comments can get out of sync with code, the tests never lie. Comments have to be maintained which is extra work. All I like to do is give a brief description of a class and describe parameters and return values for the public methods only.
I'd like some clarification on some of this if at all possible.

How can/does unit testing act as a form of documentation? Any output I have seen from unit tests thus far have basically just been "Tested this, some failed some passed" type of report.

Also, like yourself, I tend to place comment blocks before functions/methods listing params and return values etc... If you change your code to the point that you have to change your comments, then surely you also have to change your test cases? So I am unclear by the comment that "Comments have to be maintained which is extra work".

On top of those type of comments I also have a tendancy to comment parts of the code which I think may be difficult to follow. I have a tendancy to go from one extreme to the other, either being far too verbose and throwing in comments everywhere or on the flip side throwing in very little if any comments at all.

With regards writting readable code, in my opinion that's purely down to the individuals own perspective. What is readable to one may not be to someone else.
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Post by Weirdan »

I document (using javadoc notation) class & function interfaces (public and private) in both php and js (we use a lot of sophisticated js here, it must be documented too). Plus any parts that are difficult to follow.
User avatar
feyd
Neighborhood Spidermoddy
Posts: 31559
Joined: Mon Mar 29, 2004 3:24 pm
Location: Bothell, Washington, USA

Post by feyd »

I generally consider code a crime against humanity if it doesn't have some comments in it unless the code is insanely simple:

Code: Select all

echo 34;

Go Weirdan! 1900 posts! :D
foobar
Forum Regular
Posts: 613
Joined: Wed Sep 28, 2005 10:08 am

Post by foobar »

feyd wrote:I generally consider code a crime against humanity if it doesn't have some comments in it unless the code is insanely simple:

Code: Select all

echo 34;
Actually, the implications of that example are quite far reaching. Echoing the number 34 if in no context can be very confusing. I would put a comment there if the point of echoing 34 literally (which would usually be considered bad practice) would be doubtful.

Apart from these vagaries, I do the same as Weirdan. I'm now doing a collab project with someone, so I am over-commenting sometimes, just so my counterpart(s) understand my thinking.
Roja
Tutorials Group
Posts: 2692
Joined: Sun Jan 04, 2004 10:30 pm

Post by Roja »

feyd wrote:I generally consider code a crime against humanity if it doesn't have some comments in it unless the code is insanely simple:

Code: Select all

echo 34;

Go Weirdan! 1900 posts! :D
To which I would reply, what is 34?

"Magic numbers" are a crime as well, in my book.

Of course, I am no saint.. Given a choice between documenting my code, and fixing bugs in other parts, I take the latter every day of the week, and twice on Sunday!
User avatar
Luke
The Ninja Space Mod
Posts: 6424
Joined: Fri Aug 05, 2005 1:53 pm
Location: Paradise, CA

Post by Luke »

This thread has encouraged me to comment more... I don't want to have to fight any one of you guys if you come across my code some day and hunt me down for not commenting it... :?
McGruff
DevNet Master
Posts: 2893
Joined: Thu Jan 30, 2003 8:26 pm
Location: Glasgow, Scotland

Post by McGruff »

redmonkey wrote:How can/does unit testing act as a form of documentation? Any output I have seen from unit tests thus far have basically just been "Tested this, some failed some passed" type of report.
The output is indeed sparse but it's the test code itself which acts as documentation. Tests exercise the class interface in a variety of conditions thus describing the behaviour in fine detail. And because they are tests, they always do exactly what they say.
redmonkey wrote:Also, like yourself, I tend to place comment blocks before functions/methods listing params and return values etc... If you change your code to the point that you have to change your comments, then surely you also have to change your test cases?
Any comments in the code have to keep pace with edits to the class - yes. The fewer comments the less work to do. Did you mean that test cases will create extra work? There's certainly more code to write but in the long run it saves you a lot of time.
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Post by Weirdan »

McGruff wrote:There's certainly more code to write but in the long run it saves you a lot of time.
This not to diminish the significance of API docs, right? Honestly, given the choice between using a library without api documentation (but with the complete pack of tests) and using a library without any tests (but with complete API documentation) I would prefer second. Maybe that just me.

And api docs are generated from comments most of the time nowadays.
redmonkey
Forum Regular
Posts: 836
Joined: Thu Dec 18, 2003 3:58 pm

Post by redmonkey »

McGruff wrote:Any comments in the code have to keep pace with edits to the class - yes. The fewer comments the less work to do. Did you mean that test cases will create extra work? There's certainly more code to write but in the long run it saves you a lot of time.
No, what I mean't was that, you mentioned that comments need maintaining but did not mention anything about maintaining the test cases. So while maintaining comments requires work, this also extends to the test cases. Basically the quote...
McGruff wrote:Although comments can get out of sync with code, the tests never lie.
The comments only get out of sync if you don't update them, if you don't update your test cases then they too will become out of sync, essentially they wont lie, they just won't work.

I'm still not sure I see how the test cases can provide a source of documentation though. I run test scripts (not unit tests) which test the functionality of my code and generate reports on it what has been tested and the results but I don't see that helps describe the inner workings of the code. The only real benefits (other than testing/verifying your code of course) is that in most cases my test scripts also serve as example usage.
Post Reply