Skip to content
Home » Blog » More thoughts on Content Assist

More thoughts on Content Assist

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:

content assist puts a lot of space between lines in its help.

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.

source code of above comment

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.

bullet list in content assist

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:

content assist with URL links and bold

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.

Leave a Reply

Your email address will not be published. Required fields are marked *