Adding property naming standards to the MNX documentation

[samuelbradshaw]

Would it be helpful for us to add a section to our documentation with naming patterns/standards for object properties?

For example:

• Using a plural name for any properties that have an array (See Consistent Plurals (contents vs content, etc.) #300)
• Avoiding keywords in common programming languages
• kebab-case vs. camelCase vs. snake_case (In XML we tended to name elements and attributes with kebab case. In JSON, camel case or snake case is more common – do we need to switch?)
• Prefixing certain property names with an underscore or @ symbol

[mscuthbert]

I've never heard kebab case. Hilarious! So perfect.

My recommendation has been underscore case for three reasons: (1) it's been shown to be easier for non-native English speakers to read. (2) it's easier to use in case insensitive contexts. (3) it helps blind developers using screen readers.

The pros of camelCase are two: (1) save a character. (2) more JavaScript native and that's what the J in Json means.

I feel like the pros of helping diversify who programs (underscore case) outweighs saving a byte.

[samuelbradshaw]

From your underscore/snake case reasons:

(1) makes sense logically – it would be interesting to hear from any contributors who are native speakers of other languages, to get their take.

(2) There are two levels of case insensitivity:
(A) Contexts where case doesn't matter, but you can use any case and it will be preserved. This affects interoperability – if one developer puts timeSignature in their MNX file, and another developer puts in timesignature, applications may not be able to parse both. However, this could happen with snake case, too – say one developer puts in time_signature and another puts in TIME_SIGNATURE. Additionally, JSON is case sensitive, so our JSON schema should enforce whatever capitalization we settle on for either camel case or snake case.
(B) Contexts where what you type will be converted to all uppercase or all lowercase. This affects readability. If a user types timeSignature and their system converts it to timesignature, it makes it hard to read. However, I'm not aware of many modern contexts where this happens – the only example I can think of is the domain name of a URL (if you type "Google.com" it will change to "google.com").

(3) I haven't researched this much and don't have personal experience programming with a screen reader, but I'd be interested to learn more. When I searched "snake case screen reader" just now (without quote marks), the first result was, interestingly, this article that says camel case is more accessible for screen readers (not compared to snake case, but compared to all lowercase). I also found this Reddit thread where someone commented that if the screen reader is set to read punctuation, underscores could be annoying – but maybe having the underscore read makes it less ambiguous when time signature, timeSignature, and time_signature would otherwise be read the same?

EDIT: Looks like you responded below while I was commenting here. :)

[joeberkovitz]

Given the "JS" in "JSON", it is essential to make the switch from kebab-case because object property names need to be usable as legal JS variable names in order to employ the JS structuring/destructuring operators. Toy example:

  const layouts = score.getLayouts();  // get the layout of a score JSON object
  const {name, multimeasureRests} = layouts[0];  // unpacks properties of furst layout into variables

The above obviously works with underscore properties too, but not with anything like multimeasure-rests.

[joeberkovitz]

I should follow up with an observation that camel case (unlike underscores) is in some sense the “native” naming style of JavaScript as that is the identifier convention for all the built in libraries. This is part of the Java heritage of JS.

[samuelbradshaw]

I lean towards camel case as well, because it feels more native to JSON. I use both Python (usually snake case) and JavaScript (usually camel case) regularly. However, I'm interested in learning more about a couple of @mscuthbert's points before putting down a final vote.

[mscuthbert]

Well...I went to get more information to inform others and ended up being informed myself. Apparently my information about screen readers was out of date and now camel is recommended:

https://www.reddit.com/r/accessibility/comments/qwuvo0/camelcase_or_snake_case/

There was a time when screen readers would not pronounce camelCase properly. That time seems to have passed and now it's snake_case plus "read all punctuation" (essential for programming) that is more annoying for blind programmers.

I cannot find references that are not anecdotal demonstrating that one is better than the other for non-native English speakers.

Live, learn, and adjust. So I'll switch my vote to camel.

[adrianholovaty]

Camel case gets my vote as well (thanks to the various research/arguments in this discussion thread).

The one thing I'd add is: we should endeavor to sidestep the issue whenever possible. That is, we should prefer one-word property names except in cases where a one-word property name can't be avoided.