http://www.perlmonks.org?node_id=92495


in reply to The difficulties of commenting code

If you look across some modules like CGI and some other standard ones, you will notice that they have that exact same commenting style.

I bought a C++ book recently and it stated that comments may or may not be good because people might not update them and it will confuse you later. So it is at the choice of the user. In this case, it is what happened to you.

Personally, I don't comment much. I find that it doesn't help me unless I have some really complex code. Usually I have helpful variable, subroutine, and script names that will help me along my path and most of the time my code isn't too complex anyway :).

Overall, that commenting style seems to be the best decision from what I know because you might change the order or names of variables but the functionality still remains the same so the comment will never need to be changed. Thus, preventing confusion and bad comments.

UPDATE: I just noticed Iwas a little vaque in my answer. By "That commenting style" I meant like the subroutine (s)he showed above.

$_.=($=+(6<<1));print(chr(my$a=$_));$^H=$_+$_;$_=$^H; print chr($_-39); # Easy but its ok.