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.
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.
<https://xojo.com/issue/48717>
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
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.
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.
[quote=465394:@Tim Parnell]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.[/quote]
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…
[quote=465394:@Tim Parnell]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.[/quote]
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?
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.
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
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 Im 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, cant 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.
I agree completely with much that has been written above. You have this huge space [quote]Editor Area: containing layout and code editors[/quote] 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.
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.
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
Isnt it nice ?
Its 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.