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

One for the design itself and one for describing the usage at design or

runtime.

Why put the burden on code? Something like this is the programmer's responsibility, no need to add more bloat to the final code. What the program doesn't use or the user doesn't see should never be in the executable.

Smalltalk has it

Show me one example, what I know is that there's only one way to comment in Smalltalk and that makes use of class property.

User programmer can add it to Tobject via object helpers, at least in Delphi, so my answer to this question would be: no.

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.

This attitude which exists in the Pascal community needs to end.

Not really.

R.

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.

vfclists . wrote

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.

And you just said it yourself. If the developer of the code doesn't even have the time to add code comments in his code, why do you think having an "Comment" property would make it any better? It will not - the developer would still not have any time.

You don't need seperate tools to create documentation - code comments can serve as documentation. You don't even need special formatting in code comments, because tools like Lazarus IDE can read plain text comments and show them as documentation. Please try it yourself to see what I mean.

Displaying your frustration publicly is not going to change anybody's mind [as I found out many times :)], and will definitely not give the developers magically extra time to start documenting code.

If the code you are complaining about is commercial software, complain to them. If the code is from an open source project, then you and the community can start the documentation.

Regards,
- Graeme -

Enough digression - if considered carefully a comment about the

purpose of an object belongs in the object definition itself.

I use Pasdoc for that

Anyway I am not talking about documentation as such, just a property that an object can be queried about on its role, something no different from the Hint property of components, for the developer rather than the end user.

Regards,

vfclists . wrote

Anyway I am not talking about documentation as such, just a property that an object can be queried about on its role,

ie: class documentation :)

Regards,
G.

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.

I have 2 main concerns here, a comment for the component itself which is not particularly important and a comment for the component when I add it to a form or data module. When I create a method I can add a comment to the method. If I create a component in code, I can label that section of code, but if I drag and drop a component from the palette onto the form what option do I have? Descriptive variable and component names have a habit of getting too long. It is hardly for the end users sake unless the enduser is a programmer. I just need something to help when working in the IDE, eg hovering over a component and seeing the comment in addition to what is current displayed.

if one doesn't know what a component does when they drag it from the pallet, shouldn't they have the docs open which explain that component?

Descriptive variable and component names have a habit of getting too long.

agreed... i hate typing in 10+ character var or routine names... especially since i'm still working on trying to move from the old DOS TP6 environment ;)

It is hardly for the end users sake unless the enduser is a programmer. I just need something to help when working in the IDE, eg hovering over a component and seeing the comment in addition to what is current displayed.

i feel ya, man... i feel ya O:)

You can comment the variable. For example:

  Edit1: TEdit; // Now, that's a great Name

It is hardly for the end users sake unless the enduser is a programmer. I just need something to help when working in the IDE, eg hovering over a component and seeing the comment in addition to what is current displayed.

Do you mean hovering over the component in the designer? At the moment the hint shows only the caption and some common values. It could be extended to show the help for the variable. Feel free to create a feature request.

Mattias

vfclists . wrote

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.

I perfectly agree, a well formed name is worth a thousand words, in this context.

That's true, in principle; thou' you shall look at the comments also like: you cannot express the meaning and whole role of a function by its name (unless you want to couple wikipedia, of course), especially where you made some tricks that _today_ they look obvious because you're in the thing, but _tomorrow_ they might not.
I still endlessly thank myself for having put some of these comments somewhere in my code, some of 15 years ago... they helped me make the migration from DOS to Linux a little less hurting ;-)

Of course, we're talking about good and wise use of comments, which is, IMHO, still an art.

Just my 2c on this,
Al.

vfclists . wrote

It is hardly for the end users sake unless the enduser is a programmer.

we're talking about programming languages here, so that... whoever else shall an end user of a development tool/library be?!?!?!?

X_X

On Wed, Jul 17, 2013 at 3:53 AM, Mattias Gaertner <

I think he's referring to hovering over the component icon on the component pallet. Right now the tool tip shows the class name and the unit it is defined in. I think he wants it extended to include a description of the component's purpose. So hovering over the TButton icon would display:

TButton
(StdCtrls)
A push button control.

I'm all for making components more discover-able but I don't think increasing the memory footprint of every control with a comment or description field is the right solution. Using the FPDoc info already available would be a good solution. I prefer this to the JavaDoc/XMLDoc style comments in the source. I'm willing to give it a go but I've never done anything extensive with either FPDoc or the IDE internals. Anyone have a ballpark guess as to how much effort would it take to extend the tooltip for the component pallet to display the <short> tag from the FPDoc info?

Kenneth Cochran wrote

Anyone have a ballpark guess as to how much effort would it take to extend the tooltip for the component pallet to display the <short> tag from the FPDoc info?

The hint is set in unit ide/ComponentPalette, line 744 in Lazarus trunk. I don't have details for getting the FPDoc info but you can study the code yourself. It is used for example in the Object Inspector's Information Box below the properties.
I don't think the feature requires much code once you have figured out where to get the needed data. This is typical in a big project. A commit with only few lines of code has required many hours of studying the existing code.

May the source be with you! :)

Juha

Yea, I found TComponentPalette.UpdateNotebookButtons on my own in a round about way. I set a breakpoint in TControl.SetHint and launched an instance of the IDE with the debugger attached. After a half dozen hits I was into the pallet speedbuttons and checked the call stack.

Now I'm trying to track down how the source editor invokes FPDoc support when you hover over an identifier. A search for FPDoc in the source turned up the CodeHelp unit. Anyone know if I'm on the right track?

Kenneth Cochran wrote

Now I'm trying to track down how the source editor invokes FPDoc support when you hover over an identifier. A search for FPDoc in the source turned up the CodeHelp unit. Anyone know if I'm on the right track?

Yes.
See also :
TMainIDE.OIChangedTimerTimer
in unit ide/main. It updates the Object Inspector info box.

Juha