[fpc-pascal] Re: [Lazarus] Should TObject or TComponent have a Comment property?

[Kenneth Cochran]

On Fri, Jul 12, 2013 at 1:07 AM, vfclists . <vfclists at 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 at 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freepascal.org/pipermail/fpc-pascal/attachments/20130715/732f7b16/attachment.html>