Shamil Salakhetdinov
shamil at smsconsulting.spb.ru
Fri Jun 27 04:06:57 CDT 2008
Hi Gustav, I do not argue, OK? :) The point is that inline commenting is becoming less and less important/useful (and imposes too much costs to be true) as nowadays (r-)evolutionary agile Test_Driven-Design (TDD) programming practices progress: when applied by experienced agilist these practices result in small max 10-15 code lines "self-explaining" streamlined methods. Classes/Modules and Methods DO have XML comments, where the purpose of classes/modules/methods and all their parameters are described with needed level of destabilization, as well as additional remarks to explain the purpose and usage of method in details if needed are supplied but usually no inline comments in code at all. I have seen somewhere an article from Martin Fawler or maybe another famous agilist who were "pushing" this approach. And I do use it and I like it - this is why I write about it :) (IOW I'm not arguing for the purpose of "pure" arguing but I'm referring to everyday practices, which I do follow with successfully finished projects and satisfied customers with some of them being also experienced developers...) The everyday practice in TDD is that you can "mercilessly refactor" a well covered by Unit/Integration tests piece of code several times a day, and if it has inline comments then they become a trouble (they result in additional significant support costs) as you need to modify them as often as you refactor your code. But with clean streamlined code every class, interface, method, parameter is usually self-explaining therefore class level and method level comments are usually good enough... Thank you. -- Shamil P.S. Very mature IMO article on Agile and XP: "Is Design Dead?" - http://martinfowler.com/articles/designDead.html -----Original Message----- From: dba-vb-bounces at databaseadvisors.com [mailto:dba-vb-bounces at databaseadvisors.com] On Behalf Of Gustav Brock Sent: Friday, June 27, 2008 11:13 AM To: dba-vb at databaseadvisors.com Subject: Re: [dba-VB] Getting TextReader from strings... Hi Shamil Of course - and don't use dirty language. Quite a few comments to that article. This one from Solomon Grundy I like: <quote> Comments are just as important as the code itself. Otherwise you get what I call the 'Stonehenge' effect: in years to come no one will remember how to use it, or even what it does. Resulting in some coder saying, well, we just have to start all over again because this doesn't make any sense. (sort of like extreme coding, haha) The projects I lead are not complete until they are fully commented. Comments are part of the developers job, and if they can't get them done in a normal working day, that's too bad - they're either working late or taking it home. </quote> /gustav >>> shamil at smsconsulting.spb.ru 27-06-2008 01:34 >>> "Just don't overdo the comments, as comments must be maintained along with the code." http://www.theregister.co.uk/2008/03/28/case_for_comments_code/ -- Shamil -----Original Message----- From: dba-vb-bounces at databaseadvisors.com [mailto:dba-vb-bounces at databaseadvisors.com] On Behalf Of Charlotte Foust Sent: Friday, June 27, 2008 3:17 AM To: Discussion concerning Visual Basic and related programming issues. Subject: Re: [dba-VB] Getting TextReader from strings... Uh, isn't that why they invented *comments*? Properly commented geek code isn't any harder to understand later than properly commented MMW code. It's the totally undocumented stuff that makes you think of changing careers, regardless of how it's written. Charlotte Foust -----Original Message----- From: dba-vb-bounces at databaseadvisors.com [mailto:dba-vb-bounces at databaseadvisors.com] On Behalf Of Stuart McLachlan Sent: Thursday, June 26, 2008 3:33 PM To: Discussion concerning Visual Basic and related programming issues. Subject: Re: [dba-VB] Getting TextReader from strings... Even worse is when you get called back to modify the project two years later and have to try and work out what you did all that time ago :-( On 26 Jun 2008 at 18:30, Gustav Brock wrote: > simply doesn't pay off. One example is that - most of us, I guess - > often copy snippets of code from one project to another to reuse not > as is but as a skeleton for something similar. If you have to spend > several minutes just figuring out how your original code works, you > are wasting your time. The real lesson is when you after many minutes > still can't find out - that's when I stopped playing smart.