Re: Documenting Methods/Subs

The sad thing about the attitude on 'my code is self commenting' is that we use Perl for large complex projects and the code is going to live for many many years. Just because someone _thinks_ that their code is self commenting doesn't mean that they are correct.

We are looking for another Perl developer and are issuing a code test, if there aren't any comments in the code we 1: ask why and 2: put the resume on the bottom of the pile.

The primary reason is that a job interview (and the code that goes with it) should be the _best_ that you can do. I'll probably be the one tracking down your bug at midnight and uncommented code makes me very unhappy..

(of course the 'you' in the above is not being directed to anyone specific)..

Comment on Re: Documenting Methods/Subs

Replies are listed 'Best First'.
Re^2: Documenting Methods/Subs by adrianh (Chancellor) on Jan 12, 2003 at 11:14 UTC
Just because someone _thinks_ that their code is self commenting doesn't mean that they are correct. Just because somebody _thinks_ that their comment explains the code doesn't mean they are correct :-) Bad comments are just as evil as bad code. In fact they are worse, since you then have the problem of what is correct - the code or the comment. I'm not anti-comments - but they do have problems of their own which are often unacknowledged. Over the years I have found self-documenting code (tests, assertions, etc.) to be of more use in many, if not most, instances. I would also ask the coder why they didn't add comments - but I would see if they had sensible answers before consigning the resume to the bottom of the pile :-)	[reply]
Re: Re: Documenting Methods/Subs by vek (Prior) on Jan 12, 2003 at 17:50 UTC
I agree with you but I think you misunderstood my root node. I don't think you'll find many good arguments against comments in code. Comments should be used to explain why something was done a certain way or to explain a complicated alogorithm. The purpose of my root node was to ask opinions about comments prior to subroutines/methods decribing their purpose. -- vek --	[reply]