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

[vfclists .]

On 11 July 2013 23:07, Benito van der Zander <benito at benibela.de> wrote:

>  Annotations like in Java would be nice...
>
>
> On 07/11/2013 10:22 PM, vfclists . wrote:
>
>   Should TObject or TComponent have a Comment property?
>
>  I think they should. One for the design itself and one for describing the
> usage at design or runtime.
>
>  Smalltalk has it.
>
>  Consider it a version of the Hint property but for the developer
>
> --
> Frank Church
>
> =======================
> http://devblog.brahmancreations.com
>
>
> --
> _______________________________________________
> Lazarus mailing listLazarus at lists.lazarus.freepascal.orghttp://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
>
>
>
> --
> _______________________________________________
> Lazarus mailing list
> Lazarus at lists.lazarus.freepascal.org
> http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
>
>

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freepascal.org/pipermail/fpc-pascal/attachments/20130712/36f0d1b2/attachment.html>