On Sun, Mar 06, 2005 at 07:40:11PM -0500, Dossy Shiobara wrote: > 9.99 times out of 10 (feel free to round up) if the code isn't > communicating its intent, the answer is NOT to comment the code, but > to refactor it so it communicates its intent clearly. If there's a
I believe that to be a grossly innaccurate characterization. I am mildly obsessive about re-factoring and cleaning up my own code, and yet, there often still remain some critical bits which even *I*, the guy we wrote the whole thing in the first place, feel compelled to keep carefully commented just so that I myself will still understand what and why I did there a few months (occasionally years...) later. (Some typical areas for such are: communication between concurrent threads; complicated trigger-fired stuff in RDBMS systems; race conditions, atomicity, and transactional semantics; and dynamic code or query generation.) And if even I the original author need say, 5% of the code commented to stay productive, others are going to need more. Probably much more. I assert that for real-world (aka, complicated) problems, the solution-in-code tends to converge towards the maximum complexity with which the developer's mind can cope. Review and feedback from others plus refactoring helps combat that tendency, but, there's nothing inherently WRONG with that tendency! Documented human-readable design intentions - as found in good code comments - HUGELY help RAISE the maximum level of code complexity with which the developer's mind can cope, and doing so is often a LOT easier and less bug prone then thinking up some smarter way to refactor something. Such comments can also help immeasurably if/when you finally do refactor those hairy parts of the code... A codebase is a solution to a problem. I suggest therefore that attempting to artificially limit the complexity of your solution to that level which developers can understand solely from the code, WITHOUT recourse to good comments, is not a good idea, neither in practice nor in theory. Good comments let you create more sophisticated, more powerful solutions, yet still have the result be equally understandable and maintainable. Personally, I also find that the process of commenting on the current baroqueness often helps me think up better ways to solve the same problem. I think better when I'm forced to beat my thoughts into clarity on (electronic) paper. In a lousy, poorly maintained pile of spaghetti code, perhaps 99.9% of the "need why/how comments for clarity" areas really are amenable to simple immediate refactoring of the code, done so well and thoroughly that the new code then needs no further explanatory comments. But in a well-maintained codebase, that should NEVER be true. Rather, all or most of the parts which are confusing or tricky will be so because they really are solving a harder problem, and while refactoring and improving that may well be possible, it sure as heck won't be easy or trivial. -- Andrew Piskorski <[EMAIL PROTECTED]> http://www.piskorski.com/ -- AOLserver - http://www.aolserver.com/ To Remove yourself from this list, simply send an email to <[EMAIL PROTECTED]> with the body of "SIGNOFF AOLSERVER" in the email message. You can leave the Subject: field of your email blank.
