Tutorial: Providing user-friendly and flexible note-tags
When it comes to coming up with note-tags, I think one of the most important things is whether it is user-friendly or not. When you look at a script from a user’s point of view, there are several things they have to do
- Figure out what it does
- Figure out how to use it
- Writing up all those note-tags and other required inputs
- Hope it works
If it works, that’s great. But when it doesn’t work, then they have to figure out why it doesn’t work, and the worst thing is to realize an underscore was used instead of a hyphen, so why not try to make the process easier by providing flexible note-tags?
Background
Consider a simple notetag:
<custom value: 23>
The regex for this would be simple as well
/<custom value: (d+)>/
It works, and as long as users type the note-tag exactly as you have prescribed, but there are a few issues with this solution:
- It is case-sensitive. If I accidentally type “Custom” instead of “custom” this value won’t be parsed, and so “it won’t work”.
- It is space-sensitive. No space between the colon and the number? Won’t be parsed. Extra space after the number? Won’t be parsed.
Some other issues include user-preference when it comes to separating words. All of the following are possible variations that someone may naturally type
<custom value: 23> - prefers spaces <custom_value: 23> - prefers pothole case <custom-value: 23> - prefers hyphens <customValue: 23> - prefers camelcase or pascal case
Specific characters aside, some people might just like to line everything up neatly:
<custom value: 112> <custom value: 23>
Techniques
My choice of note-tagging addresses all of these possible preferences. Although it makes the regex look unnecessarily long, it does not take much effort to write or maintain. The same note-tag I presented above would be parsed using this regex:
/<custom[-_ ]?value:s*(d+)s*>/i
Things to note:
I allow users to choose between a hyphen, underscore, space, or no separator at all.
[-_ ]?
I allow users to choose how much white-space they want before and after the data
s*
I allow users to choose whatever case they want to type in with the `i` modifier at the end of the expression.
Closing
There are of course many more things you could do to make your note-tags flexible, such as allowing users to split it across multiple lines, or adding support for white-space in various places. Some users might prefer to use a completely different set of characters to separate words.
I would typically just go with the tips shown above as I don’t think it is necessary to do much more beyond that. The purpose is to reduce the chances of user-error, and those are probably the more common issues.
How nice, thanks! =)