Why not write self-documenting code?
In my opinion programmer's goals should be: efficience,
maintainability, readability. Not necessarily in this
Artificial languages are supposed to be used to
communicate with humans, not only with machines.
I strive to write self documenting code, but I also like to fill in with helpful comments. When I use a code snippet that I had to look up, I usually put a comment in explaining it. This leads to the funny situation of going back to maintain a bit of code written months prior, and finding comments like, "@_ is the input array to the subroutine" just before a line like "my ( $name, $rank, $serialnumber ) = @_;". I didn't know that when I wrote it, but I do now. Someone new to perl will appreciate that line when they have to work on the code, but an old timer would think it was written by an idiot. (No, not an idiot. A newbie... but sometimes we mistake ignorance for idiocy)
But yes, writting self documenting code is very important. Thats why I use constant.pm instead of writing the routines myself and why I didn't use a regex in my answer to One for the regexp fans
When you write any documentation you have to assume some level of information that the future reader might have on the subject.
Obviously this is not only a problem with Perl.
My first comments are nearly useless to me now (or just plain stupid). But on the other hand those scribblings are self-documenting because they are that simple.
Nowadays, though I am far from beeing really good, I want to include pod in my code and when I think the code may be used or reviewed by a complete novice I add comments of the redundant form.
I wrote I want to, but it still is an excercise in self discipline.
It is far quicker to just enter a few comments.