Make any user-facing language as clear as possible.
Limit jargon and overly technical language (using pre-existing HQ terms is okay)
Don’t let internal names bleed into user-facing content
“Lookup tables” not “fixtures”
“Web apps” not “cloudcare”
“Mobile worker” not “mobile user” or “CommCare User”
All user-facing text should be translated with
Strings that contain variables should use
_.templateas described in the translations docs.
All user-facing dates and times should be displayed in a time zone that will make sense for the user. Look at usage of
UserTimeand more generally at
<%- ... %>in Underscore templates to HTML escape values.
DomPurifyto HTML escape user input that will be displayed, but not in a template.
Delays and Errors
Any potentially long-running requests, including all AJAX requests, should use a spinner or similar indicator.
disableButtonto disable & add a spinner, then
enableButtonwhen the request succeeds or fails.
Knockout: These usally need custom-but-usually-short disable/spinner code, probably using a boolean observable and a
disablebinding in the HTML.
There may not be spinner/disable code if there’s an HTML form and it uses the
Any AJAX requests should have an
This usually doesn’t need to be fancy, just to display a generic “Try again”-type error near the action that was taken. Most requests aren’t error-prone, this is typically just to defend against generic platform errors like the user getting logged out.
first_namein the same file. Find a synonym for one of them.
Avoid long lists of params. Prefer kwargs-style objects and use
assert_propertiesto verify they contain the expected options.
Make sure any js access of initial page data is guaranteed not to happen until the page is fully loaded. Not doing so risks a race condition that will break the page. Keep an eye out that any new initial page data accessed in js is made available in HTML (usually not an issue unless the author didn’t test at all).
Prefer knockout to jQuery. Avoid mixing knockout and jQuery. Recall that you don’t have to solve the author’s problems. It’s enough to say, “This is a lot of jQuery, have you considered making a knockout model?”