search

microsoft / jacdac

Device and service catalogs for Jacdac.
https://aka.ms/jacdac
Creative Commons Attribution 4.0 International
66 stars 25 forks source link

naming rules #67

Closed pelikhan closed 3 years ago

pelikhan commented 3 years ago

We need to specify rules for name:

mmoskal commented 3 years ago

I think we should definitely limit the identifiers (I was thinking 31 characters), and enforce [a-zA-Z][a-zA-Z0-9_]* on them (which I think we do).

The snake case names have more information than camel case (eg. get_XML_payload -> getXMLPayload -> get_x_m_l_payload)

pelikhan commented 3 years ago

Snake or camel?

jamesadevine commented 3 years ago

I personally vote for Camel. It separates words without additional character overhead!

mmoskal commented 3 years ago

as I said, you can convert from snake to camel, but not the other way around, because of the lacking "overhead"

jamesadevine commented 3 years ago

Thanks for describing in words what your "e.g." meant!

If snake case makes it easier to translate to different programming languages where conventions are different, then sure, snake case sounds good. You'll be eating into that 31 character limit though.

mmoskal commented 3 years ago

the longest words in the spec right now is 30 characters:

      1 W 16 connection_error
      1 W 16 firmware_version
      1 W 16 method_call_body
      1 W 16 subscribe_method
      1 W 16 twin_update_json
      1 W 17 InvalidPageOffset
      1 W 17 actual_brightness
      1 W 17 auto_invoke_every
      1 W 17 connection_status
      1 W 17 connection_string
      1 W 17 current_iteration
      1 W 17 list_stored_roles
      1 W 17 respond_to_method
      1 W 17 samples_in_window
      1 W 17 sampling_interval
      1 W 18 IEEE_802_LongRange
      1 W 18 device_description
      3 W 18 streaming_interval
      1 W 19 EdgeImpulseCompiled
      1 W 19 OutOfFlashableRange
      2 W 19 firmware_identifier
      1 W 19 list_required_roles
      1 W 20 allocated_arena_size
      1 W 20 keep_on_pulse_period
      1 W 21 InvalidCommandPayload
      1 W 22 devicebound_properties
      1 W 22 keep_on_pulse_duration
      1 W 24 HasSecondaryChannelAbove
      1 W 24 HasSecondaryChannelBelow
      1 W 30 bootloader_firmware_identifier

I feel letting people use more than ~30 will lead to terrible names. Already some of these names (devised by yours truly) are kind of weird and long.

jamesadevine commented 3 years ago

@mmoskal Agreed, concise is good. Are we also thinking about alternate spoken/written languages? (e.g. mandarin, french etc.) I assume you're thinking this would be translated into different languages using the mechanism described above?

mmoskal commented 3 years ago

These are identifiers, like API names; I've never seen these translated. The descriptions could be translated at some point.

pelikhan commented 3 years ago

In that DTDL reference, they support localized strings for user facing data -> https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/dtdlv2.md#display-string-localization

pelikhan commented 3 years ago

31 it is.