Recently I write about best practices for commenting for content assist. I’ve been writing a lot of LotusScript recently (I’m making a present for you), and in trying to make the content assist as helpful as possible, I’ve had some additional thoughts.
Use long lines in comments
It’s unhelpful that the IDE considers each line a separate paragraph and inserts spacing between, like this:
This is where a line break appears in the code, but there the lines are close together and the indentation provides a guide to what should be grouped together.
To fix this, I’ve been just writing really long lines in the comments. If I intend something to be a paragraph, I put it all on one line. This does make it a little harder to read in the IDE, but I figure people will be using this API a lot more than they’ll be editing the code of it, so I’m okay with that.
Incidentally, you can set the LotusScript editor to wrap long lines using the key combination Alt+Shift+Y.
Make bullet lists
Referring back to the above illustrations, notice the list or arguments (or in this case, list of argument) is indented in the comment, but the indentation is lost in the content-assist version. I think it’s nice to turn these into bullet lists so there’s a visual indication these are sub-items.
I just inserted bullet-like characters into the text here, but there’s more…
Links and formatting
Here’s something I discovered by accident. Content assist treats the header comment as HTML. This, again, is a bit of a mess when you view the source code, but look:
Notice I have bolded a couple of words and yes, that link does work — but in the same popup window, so it might be good to include the URL as text, as I have not done in this case, so people can also copy it into their browser for an easier reading experience.
In closing
Again, this is for an API that I really want to maximize for programmer ease of use. The above measures might be a little extreme for routine projects. But please do consider and use them where appropriate.