Property Comments - Xojo Forum

7 months ago

Robert W
27 Nov 2019 Western Canada

Edited 7 months ago

I don't think I've ever seen a discussion of this, or seen anything in the documentation about this, but I'm sure that everyone on the forum is aware of this.
If you create a property in your project (either in a window or class or app), you can type some text in the code editor window, and it will be saved when you save your project, and magically reappear when you open it again. This would seem to be an ideal way to add a comment about the property. Except, as I mentioned above, I've never seen anything in the documentation to suggest doing this. So, I'm wondering, since it appears to be undocumented, is it safe to put comment text in the code editor window? If it is (or isn't), how many of you take advantage of this to document your properties?
Context:
Being somewhat hard of thinking, I probably overdocument my code, because I know that a week after I write something, I'll have no idea how it works unless there are two comments for every line of source code.
Emile S
28 Nov 2019 Europe (France, Strasbourg)

This is know and existsed in REALbasic / Real Studio.
Yes, usefull. Sometimes I even add where it is used (of course after I explain its meaning / use).
Same kind are the Notes.
Kevin G
28 Nov 2019 Xojo Pro Gatesheed, England

I added a request back in 2017 & 2019 to improve the documentation of methods and to add the ability to document parameters and the return.
Feedback Case #48717

· Robert L and Markus R like this.
Rick A
29 Nov 2019 Testers, Xojo Pro (Brazil. UTC-3:00)

I always do that, also I do prefix the comment with a // just in case for enhanced security reasons.
Julia T
29 Nov 2019 Sandy Hook, Connecticut

It's not well-known, but you can also comment constants by using the usual '//' in the Default Value field in the Inspector.
Dave S
29 Nov 2019 San Diego, California USA

@Julia T It's not well-known, but you can also comment constants by using the usual '//' in the Default Value field in the Inspector.
Julia... have you tried that?
If the varialbe is a STRING then its value is your "comment" (unless you immediately assign a new value)
if you change it to another datatype it removes your "comment" because it doesn't match the indicated datatype
Rick A
29 Nov 2019 Testers, Xojo Pro (Brazil. UTC-3:00)

@Julia T you can also comment constants by using the usual '//' in the Default Value field in the Inspector.
I do recall doing something like that in the past, but probably a bug, right now the IDE does not allow me to put a value like "0 // comment" in the Default of a integer for example.
Julia T
29 Nov 2019 Sandy Hook, Connecticut

Well, it works for numbers anyway.
I used to do it all the time in RS, but like so many other nice features, it may be compromised in Xojo.
Rick A
29 Nov 2019 Testers, Xojo Pro (Brazil. UTC-3:00)

Edited 7 months ago

In constants and enums I believe the IDE "lets" you put such values.
Tim P
29 Nov 2019 Testers, Xojo Pro Rochester, NY

Edited 7 months ago

You can also use reserved keywords like new in the enum editor. It's just that the enum and constant editors are incomplete and are missing some aspects of the field validation.
If I were you, I would not rely on this behavior.
Karen A
29 Nov 2019 Testers

@Tim P You can also use reserved keywords like new in the enum editor. It's just that the enum and constant editors are incomplete and are missing some aspects of the field validation.
If I were you, I would not rely on this behavior.
You can also do that for structure members IIRC.
It is certainly handy for documenting things so I would not call being able to put comments in such definitions a bug...
Even if it originally was bug it's now a feature! ;)
-karen
Martin T
29 Nov 2019 Testers Germany

@Tim P You can also use reserved keywords like new in the enum editor. It's just that the enum and constant editors are incomplete and are missing some aspects of the field validation.
If I were you, I would not rely on this behavior.
You did? I recently had the problem that the compiler of an enumeration called To or Event didn't want and I had to rename them.
If I interpret your statement correctly, is it possible to use these names? If so, how?
Tim P
29 Nov 2019 Testers, Xojo Pro Rochester, NY

@MartinTrippensee You did? I recently had the problem that the compiler of an enumeration called To or Event didn't want and I had to rename them.
Yes, if the editor were operating correctly, you wouldn't be able to enter them at all. The same behavior as the name of a control or class.
@Martin Trippensee If I interpret your statement correctly, is it possible to use these names? If so, how?
No, you misunderstood - and that you want to find a way to use them is alarming.
Martin T
29 Nov 2019 Testers Germany

@Tim P No, you misunderstood - and that you want to find a way to use them is alarming.
Why is that alarming? I don't understand why the compiler prevents the execution if, for example, MyEnumerationTypes.Event is uniquely assigned. It is obvious that this is an enumeration and not an event.
Norman P
29 Nov 2019 Testers, Xojo Pro outside admiring the sunshine,...

In an Enum its impossible for a value named the same as a keyword to be misinterpretted since you always have to prefix it with the enumeration name to refer to a specific value
I reported a bug with this
Feedback Case #56375

· Martin T likes this.
Craig H
29 Nov 2019 Black Hills, SD, USA

@Robert W ...If you create a property in your project (either in a window or class or app), you can type some text in the code editor window, and it will be saved when you save your project, and magically reappear when you open it again. This would seem to be an ideal way to add a comment about the property. ...
Thanks for asking as I have had the same question. I remember that as a beginner, this large blank space seemed a bit imposing, as though inviting you to enter something. I also recall finding no mention in the documentation. I have been using it extensively for making notes and would find it irksome if it just went away on some future release.
Unless I’m mistaken about the lack of documentation, XOJO should include some for this feature.

As Rick A. mentioned, I also as a precaution made every line a commnent, but stopped the practice when I realized I could have auto-complete. (Why, again, can’t we have the option of auto-complete within a comment)?
Note that there is a “Description” field in the IDE inspector (showing one line, but supporting multi-lines) for properties, methods, constants, event handlers, etc. , usually/always located on the “gear tab” panel. It shows by default for Event Handlers which only have the ‘gear’ panel). The Description field may be a convenient place to keep notes, though it appears that the contents are not printed when one prints out code, whereas the bonus Properties area appears to be printed. Also, I suspect that most of us would want to have more that a single line visible by default.

· Robert L likes this.
3 months ago

Robert L
Apr 12 XDC Speakers Federal Way, WA (Seattle Area)

Unless I’m mistaken about the lack of documentation, XOJO should include some for this feature.
I agree completely with much that has been written above. You have this huge space
Editor Area: containing layout and code editors
as it is described in the documentation associated with Properties but as far as I can tell its purpose in the context of a Property is never explained in the documentation. I think that basically it has no designated purpose in this context.
This should be embraced as a place to put notes (presumably about the Property). It is vaguely discomforting for my personality type to write in this vast space which happily accepts and remembers my text in the absence of any documentation or assurance that this "proper" and will not disappear in some future release. It is much more convenient than creating a "proper" note with the name of the property and then putting your explanatory text there.
Robert L
Apr 12 XDC Speakers Federal Way, WA (Seattle Area)

It does have some peculiar features when used as a comment area. Words like is and or get auto capitalized just to remind you that what you are doing isn't really orthodox. Someone mentions above using the "comment" marker ( // ) before the lines and this alleviates this distraction.
Emile S
Apr 12 Europe (France, Strasbourg)

If making comments there bother you, add a note and in the Name location, use “Property” followed by a space, then the name of the Property as used, then, in the comments part, add whatever text you want / need / feel is appropriate…
Isn’t it nice ?
It’s like a name convention in Properties / Method/Function / Windows, etc… each of us have its own.
I am sure there are people who do not explain what a Method/Function do in that area but in a Note to have a cleaner code area. ;)
Wayne G
Apr 12 Testers, Xojo Pro, MVP Auckland, New Zealand

Properties & Constants also have a description field in the advanced section of the inspector.

· Robert L likes this.
Newer ›