Do you comment your code?
Moderator: General Moderators
Do you comment your code?
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.
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.
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.
- Chris Corbyn
- Breakbeat Nuttzer
- Posts: 13098
- Joined: Wed Mar 24, 2004 7:57 am
- Location: Melbourne, Australia
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
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
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.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.
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.
- feyd
- Neighborhood Spidermoddy
- Posts: 31559
- Joined: Mon Mar 29, 2004 3:24 pm
- Location: Bothell, Washington, USA
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!
Code: Select all
echo 34;Go Weirdan! 1900 posts!
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.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;
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.
To which I would reply, what is 34?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!
"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!
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: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.
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.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?
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.McGruff wrote:There's certainly more code to write but in the long run it saves you a lot of time.
And api docs are generated from comments most of the time nowadays.
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: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.
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.McGruff wrote:Although comments can get out of sync with code, the tests never lie.
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.