Page 1 of 2
Do you comment your code?
Posted: Thu Nov 10, 2005 12:58 pm
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.
Posted: Thu Nov 10, 2005 1:12 pm
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.
Posted: Thu Nov 10, 2005 1:13 pm
by foobar
No comments => uber n00b
Posted: Thu Nov 10, 2005 1:21 pm
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...
Posted: Thu Nov 10, 2005 1:58 pm
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

Posted: Thu Nov 10, 2005 2:08 pm
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.
Posted: Thu Nov 10, 2005 2:31 pm
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.
Posted: Thu Nov 10, 2005 4:15 pm
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.
Posted: Thu Nov 10, 2005 4:18 pm
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:
Go Weirdan! 1900 posts!

Posted: Thu Nov 10, 2005 4:39 pm
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:
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.
Posted: Thu Nov 10, 2005 4:40 pm
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:
Go Weirdan! 1900 posts!

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!
Posted: Thu Nov 10, 2005 5:24 pm
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...

Posted: Thu Nov 10, 2005 5:33 pm
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.
Posted: Thu Nov 10, 2005 5:56 pm
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.
Posted: Thu Nov 10, 2005 6:06 pm
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.