On Fri, Jul 12, 2013 at 1:07 AM, vfclists . <vfcli...@gmail.com> wrote:
> > 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 > > 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. > > Instead of doing the simple thing a purist attitude has been adopted which > never does anyone any good. > > 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. > > 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. > > There is a totally insane disconnect here. The Smalltalk guys got it right. > > There can be an options to strip the comments out in the final deliverable > just like the debugging information. > > -- > Frank Church > > ======================= > http://devblog.brahmancreations.com > > _______________________________________________ > fpc-pascal maillist - fpc-pascal@lists.freepascal.org > http://lists.freepascal.org/mailman/listinfo/fpc-pascal 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.
_______________________________________________ fpc-pascal maillist - fpc-pascal@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-pascal