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

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.

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.

No.
It takes memory and needs management. Putting this in a basic class such as TComponent is not an option. Your suggestion to 'not store it in the final executable' is not even remotely possible.

You can put a comment in front of the object or any of its properties, and the lazarus IDE will display this comment for you.

It does not take memory, and performs the same function. The only reason the smalltalk people didn't take that approach, I suppose, is because they don't have an intelligent IDE.

Michael.

LOL. The Smalltalk IDE "IS" the original IDE and over 30 years later it is yet to be matched for functionality and practicality.

This comment issue is like approaching a person on the street and asking him "What is your occupation?" - and he doesn't can't tell you. You can only look at his name badge if he is wearing one, and find out from some authority who he might be, assuming you know who and where to ask.

Yet they didn't find it possible to intelligently make use of comments in code ?

Curious, to say the least ?

This comment issue is like approaching a person on the street and asking him "What is your occupation?" -  and he doesn't can't tell you. You can only look at his name badge if he is wearing one, and find out from some authority who he might be, assuming you know who and where to ask.

What kind of remark is that ?
His occupation is none of your business to begin with.

In each case,
a) Your proposal will not be done for sound technical reasons. b) The Lazarus IDE offers an excellent alternative. c) The new property would be useless if people don't use it, and backfitting the many thousands of components so it actually uses the new property is a huge task, which I do not see happening anytime soon. d) You can perfectly create a descendent of TComponent that introduces it and use it in all your projects.

Michael.

The comments are stored directly with the code itself and the IDE is designed to extract them automatically. The execution environment and the development environment are the same thing. A shipping system can be purged of unnecessary information for delivery to the customer but they are virtually the same, or compiled to machine code if so desired.

Say it was a factory you owned and the person is from some department or a job agency. Could you even call them your employees? Where is the immediacy?

At the end of the day there is a deeper philosophical issue here. An IDE user is like a spreadsheet user, he is both a developer and consumer and he shouldn't have to revert to primitive or external tools to customize or gain immediate functional insight the very tools and program libraries he is working with.

In our previous episode, vfclists . said:

If you get deep and philosophical, you must first question your first assumption, namely that documentation should be prefer some separation between documentation and source. Yes, it is a lofty goal to edit them at the same time, but embedding the documentation into the source is then only the way of the least resistance. Not the best way.

vfclists . wrote

At the end of the day there is a deeper philosophical issue here. An IDE user is like a spreadsheet user, he is both a developer and consumer and he shouldn't have to revert to primitive or external tools to customize or gain immediate functional insight the very tools and program libraries he is working with.

Exactly. He does not need to.

The lazarus IDE already does it all for him. Great, isn't it ?

Michael.

Michael Van Canneyt wrote

You can put a comment in front of the object or any of its properties, and the lazarus IDE will display this comment for you.

Although if I recall correctly somebody was going to look at this and do a bit of cleaning up. For example, if a procedure is annotated with a "boxed" comment (this will probably wrap):

(* Apply the Tiger2 hash function to the sequence of strings passed as
the      *)
(* parameter, the final one is to be used as padding. The result is
returned    *)
(* with base-64 encoding and trimmed to 24 characters.
         *)
//
function Tiger2x64_24(const raw: array of string): string;

it requires that this be made contiguous by // or similar, and even then displays a spurious " (Source)" after each comment line.

How do you know which object to use if the documentation isn't in a separate, searchable file or website? Just query objects at random until you find what you need? How do you even know what the available objects are? Also, many people still use a lot of procedural code. Where is their documentation since there is no object in the first place?

Can't see in any way how this proposal makes things better instead of worse.

Yes, there must be no empty lines between the comment(s) and the declaration.

and even then displays a spurious " (Source)" after each comment line.

That is a hyper link to the source. For example when you install the turbopoweripro design package the hints are HTML with clickable links.

Mattias

Ah. Couldn't that be replaced with a less-obtrusive Unicode glyph i.e. like a Wiki marks external links?

I don't consider this a good idea. Properties can only be filled in the implementation section or using resources (e.g. LFMs) (I ignore the "default" modifier for now).

If you want comments for classes, properties, etc. then use attributes (once the branch is merged to trunk):

=== code begin ===

type
   [TComment('This class does something really awesome')]
   TMyClass = class
     [TComment('This property does this and that')]
     property SomeProperty: ...
   end;

=== code end ===

(this might be the only case were I'd consider the attributes *before* an identifier advantagous)

Regards,
Sven