Standardize case of labels, names, ids to camel case

[GoogleCodeExporter]

Proposed rule: 
Names, titles, gml ids, and other attributes meant as human readable labels 
should have camel case. An exception is made for labels containing the short 
version of an identifier or definition URI that contains underscores (e.g. 
air_temperature, station_12, etc). Another exception is made for network-all.

This issue evolved from a discussion on Issue 19:
http://code.google.com/p/ioostech/issues/detail?id=29

Original issue reported on code.google.com by sh...@axiomalaska.com on 30 Sep 2012 at 12:51

[GoogleCodeExporter]

Text in current templates that would be changed:

GetObservation:
observedproperties1 -> observedProperties1

DescribeSensor:
deployment_start -> deploymentStart
deployment_stop -> deploymentStop
<sml:component name="Sensor watertemp1"> -> sensorWatertemp1
<sml:System gml:id="sensor-watertemp1"> -> sensorWatertemp1
<sml:output name="Water Temperature"> -> waterTemperature
<sml:component name="Sensor ct1"> -> sensorCt1
<sml:System gml:id="sensor-ct1"> -> sensorCt1
<sml:output name="Water Temperature"> -> waterTemperature
<sml:output name="Salinity"> -> salinity
<sml:component name="Sensor baro1"> -> sensorBaro1
<sml:System> -> sensorBaro1
<sml:output name="Barometric Pressure"> -> barometricPressure
<sml:component name="Sensor airtemp1"> -> sensorAirtemp1
<sml:System gml:id="sensor-airtemp1"> -> sensorAirtemp1
<sml:output name="Air Temperature"> -> airTemperature

sml:component's name and sml:System's gml:id become redundant here, so we could 
make another exception to allow for different formatting.

Original comment by sh...@axiomalaska.com on 30 Sep 2012 at 12:51

[GoogleCodeExporter]

This is both a note to self and encouragement/prodding to others to comment on 
this issue, regarding naming conventions for various labels, names and id's. 
And thanks again to Shane for having pointed this out and submitted & 
documented the issue.

Original comment by emilioma...@gmail.com on 12 Oct 2012 at 11:18

[GoogleCodeExporter]

I agree with this stylistic convention and would recommend we adopt it with one 
caveat.  This style convention doesn't extend to controlled vocabularies of any 
kind.  They have their own style conventions and we shouldn't mess with them.  
For example, the CF Standard name for sea water temperature is:

sea_water_temperature NOT seaWaterTemperature.

1. Can someone recommend a good reference for camel case (or is it upper camel 
case?)
2. Where does this belong on the wiki?  SOSGuidelines? 

Original comment by dpsnowde...@gmail.com on 23 Oct 2012 at 5:32

[GoogleCodeExporter]

How are we to handle names that begin with an acronym?

Example:

Does "PAROS Serial Number" become "PAROSSerialNumber" or "parosSerialNumber"?

Another example is "BPR Location".

Original comment by mike.gar...@gmail.com on 23 Oct 2012 at 5:57

[GoogleCodeExporter]

Derrick: Agreed. This was implied in the original discussion but not documented 
here. Revised rule:

Names, titles, gml ids, and other attributes meant as human readable labels 
should have camel case. An exception is made for labels containing the short 
version of an identifier or definition URI that contains underscores (e.g. 
air_temperature, station_12, etc). Another exception is made for network-all. 
This rule does not apply to actual identifier values and terms from established 
vocabularies (e.g. http://mmisw.org/ont/cf/parameter/air_temperature or 
urn:ioos:station:xoos:the_station).

Mike: Good question about the acronymns. Do you have a preference? 
parosSerialNumber seems more readable to me...

Original comment by sh...@axiomalaska.com on 23 Oct 2012 at 6:15

[GoogleCodeExporter]

Shane:  I had already coded them as parosSerialNumber and bprLocation.  Just 
wanted to run it by y'all though.  It seemed a bit off at first but it is 
readable.

Original comment by mike.gar...@gmail.com on 23 Oct 2012 at 6:45

[GoogleCodeExporter]

Mike: It looks exactly right to me as it is in line with the rule, and this is 
not a glossary where they must look authentic.

Original comment by abir...@gmail.com on 23 Oct 2012 at 7:04

[GoogleCodeExporter]

Revised rule:

Names, titles, gml ids, and other attributes meant as human readable labels 
should use lower camel case. An exception is made for labels containing the 
short version of an identifier or definition URI that contains underscores 
(e.g. air_temperature, station_12, etc). Another exception is made for 
network-all. This rule does not apply to actual identifier values and terms 
from established vocabularies (e.g. 
http://mmisw.org/ont/cf/parameter/air_temperature or 
urn:ioos:station:xoos:the_station). Text containing acronyms should treat the 
acronym component as a normal word for readability (e.g. bprLocation instead of 
BPRLocation).

As suggested by Derrick, this issue will close by Thursday. If anyone has 
further feedback, let's hear it now.

Original comment by sh...@axiomalaska.com on 23 Oct 2012 at 10:01

[GoogleCodeExporter]

Shane, if you close this issue some time on Thursday 25-Oct-2012, please 
include a reference to the wiki page on which the rule is documented.  

FYI, there is a related comment about Upper Camel Case at 
https://code.google.com/p/ioostech/wiki/SOSGuidelines_final#Capitalization_of_Ke
yword_Value_Pair_(KVP)_names_and_values 
Can you check to see if this text is consistent with your proposal?  

If you think that this style convention is something that will be elaborated 
upon or added to then maybe we need a new page.  Otherwise, it can just be a 
section on an existing page.  We currently have SOSGuidelines and 
SOSGuidelines_final.  The content  on the latter is most up to date, but it 
will be migrated to the former soon.  And then deleted.

Alternatively, I was thinking that a new page called SOSTemplates might be 
warrented.  This page would be a landing page for the requirements and design 
process for each new release of the templates and can be written so as to be 
distinct from the SOSGuiedlines which is more about the SOS interface.  Clearly 
the response information on SOSGuidelines should point to SOSTemplates where 
necessary.  This is evolving into another issue!!!   

Original comment by dpsnowde...@gmail.com on 24 Oct 2012 at 1:55

[GoogleCodeExporter]

Closing. This issue only applies to attributes inside SOS XML documents so KVPs 
in GET requests aren't affected.

To avoid adding to the wiki sprawl, for now I just added a Rules section to 
SosGuidelines_final 
(http://code.google.com/p/ioostech/wiki/SOSGuidelines_final?ts=1351269275&update
d=SOSGuidelines_final#Rules).

Original comment by sh...@axiomalaska.com on 26 Oct 2012 at 4:39

• Changed state: Done