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

[Benito van der Zander]

 >Enough digression - if considered carefully a comment about the 
purpose of an object belongs in the object definition itself.

I use Pasdoc for that

On 07/12/2013 08:07 AM, vfclists . wrote:
>
>
>
> On 11 July 2013 23:07, Benito van der Zander <benito at benibela.de 
> <mailto: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 list
>>     Lazarus at lists.lazarus.freepascal.org  <mailto:Lazarus at lists.lazarus.freepascal.org>
>>     http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
>
>
>     --
>     _______________________________________________
>     Lazarus mailing list
>     Lazarus at lists.lazarus.freepascal.org
>     <mailto: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
>
>
> _______________________________________________
> fpc-pascal maillist  -  fpc-pascal at lists.freepascal.org
> http://lists.freepascal.org/mailman/listinfo/fpc-pascal

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freepascal.org/pipermail/fpc-pascal/attachments/20130712/823b1533/attachment.html>