|Welcome to the Monastery|
Re: Re: Reasons for looking at your favourite module's sourceby BrowserUk (Pope)
|on Sep 12, 2003 at 19:56 UTC||Need Help??|
It's strange, but no matter how many times I see the arguments for "lots of comments", no matter how well argued they are, nor matter whether the proponents are those I have great respect for or not, I always end up with the same thought running through my brain.
If I cannot understand the code without reading the comments, then I need to work out how that code works, for myself, without hints, otherwise I won't really understand it, and therefore risk breaking it when the time comes to modify it. This is true whether then code in question is old code of my own, or code I get from someone else.
For me, this is a little like driving a car without having an appreciation of what goes on under the bonnet (or in the EMU or ABS etc.). Many people are quite happy to be oblivious to the details, and are quite comfortable with just knowing that the feature is there and working on their behalf, but I just have to know how it works.
I realise that this is indicative of (another) character flaw in myself, rather than a condemnation of others, but that's just how I am.
That's why I tend to stick to the occasional comment in my code of the form "This next bit does such and such", rather than copious explanations of every routine or block. These act as flags that draw my attention to those bits of the code that will probably require some effort on my part to understand again in 2 years time. As such, they serve a higher purpose than just explaining the code, they draw attention to those bit that need explanation.
My tendancy to remove overly copious comments from other peoples code and read the code rather than the comments comes from several, painful examples where the comments were innaccurate, out of date, or just plain wrong that caused me personal and/ or profesional grief.
I had one person say that "Of course you shouldn't believe the comments verbatim, you should always check that the code does what the comment say!".
My only response to that is: In that case, what damn purpose do the comments serve?
This is a very personal viewpoint, and not one I expect many people to share, but until someone devises a mechanism for testing the comments along with the code, I will continue to believe only what the code tells me, and will, at best, ignore the comments, but if they are too copious
and therefore distract from my overview of the structure of, and close-up view of the detail of, the important stuff, IE the code, then I will delete them.
My editor macro for doing this in perl code is beginning to get quite clever:)
Examine what is said, not who speaks."Efficiency is intelligent laziness." -David Dunham
"When I'm working on a problem, I never think about beauty. I think only how to solve the problem. But when I have finished, if the solution is not beautiful, I know it is wrong." -Richard Buckminster Fuller
If I understand your problem, I can solve it! Of course, the same can be said for you.