<div dir="ltr"><br><div class="gmail_extra"><div class="gmail_quote">On Fri, Jul 12, 2013 at 1:07 AM, vfclists . <span dir="ltr"><<a href="mailto:vfclists@gmail.com" target="_blank">vfclists@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div class="h5"><div class="gmail_extra"><br></div></div></div><div class="gmail_extra">This attitude which exists in the Pascal community needs to end. I say Pascal not FreePascal because when I examine a lot of free Delphi libraries I see the same thing. Lots and lots of code and not a comment in sight. It makes stuff needlessly difficult. The simple fact is documentation is never going to happen because no one has time to create it with separate tools, not even the people writing the code themselves. Coding time is the best time for documentation because that is when the intent of the code is clear and fresh in the developers mind, and incurs minimal additional cost. After all it takes barely a minute or two to describe a function, and the same parsing tools compiling the code can pull out the comments and create documentation stubs if there is a need to flesh them out further, eg with examples etc<br>
<br>Even a lot of the funded open source libraries don't have the resources to create proper documentation. If you take Delphi for instance, since Turbo Pascal, Delphi 7 etc the quality of documentation has gone down and these are companies that are well funded.<br>
<br>Instead of doing the simple thing a purist attitude has been adopted which never does anyone any good.<br><br></div><div class="gmail_extra">It is time developers learn to treat other developers as consumers not people who are supposed to RTFC or RTFM. Developers are people who are supposed to put parts together just by examining the function parameters and the function descriptions rather than wade through loads of procedure definitions and sample code full of similar sounding and confusing names.<br clear="all">
</div><div class="gmail_extra"><br></div><div class="gmail_extra">Enough digression - if considered carefully a comment about the purpose of an object belongs in the object definition itself. Why should interrogation about an object's purpose be handled by a whole subsystem of code which has precisely nothing to do with the object, ie the operating system, a help displaying program, a filename which is the help document, as well as a search string which is the object's name? Multiply that by the variety of help displaying programs for each operating system, then by the number of operating systems available then you can see how ridiculous the whole concept is. Just bureaucracy piled on bureaucracy and attachment to ill thought out convention and tradition. There is never a direct link between an object and the help display programs available on the operating system.<br>
<br>There is a totally insane disconnect here. The Smalltalk guys got it right.<br><br></div><div class="gmail_extra">There can be an options to strip the comments out in the final deliverable just like the debugging information.<br>
</div><div class="im"><div class="gmail_extra"><br>-- <br>Frank Church<br><br>=======================<br><a href="http://devblog.brahmancreations.com" target="_blank">http://devblog.brahmancreations.com</a>
</div></div></div>
<br>_______________________________________________<br>
fpc-pascal maillist - <a href="mailto:fpc-pascal@lists.freepascal.org">fpc-pascal@lists.freepascal.org</a><br>
<a href="http://lists.freepascal.org/mailman/listinfo/fpc-pascal" target="_blank">http://lists.freepascal.org/mailman/listinfo/fpc-pascal</a></blockquote><div><br></div><div> </div></div>I completely disagree. It is the code that is the primary expression of intent not the comments. This is mainly accomplished through sensible identifier naming. Comments exist to compensate for a developer's inability to express intent through the code and IMHO should be reserved for this sole purpose. In most cases you should be able to look at a function signature and know exactly what that function's intent is. Likewise you should be able to tell the intent of a class by its name and the names of its public/published members. This is, at least, what I strive for in my own code. Bob Martin's "Clean Code" dedicates the entire 4th chapter to the discussion of comments and make some very compelling arguments for limiting their use.</div>
</div>