Specification should recommend function names

[fulldecent]

The specification at https://github.com/google/open-location-code/blob/master/docs/specification.md

defines required functionality (e.g. function) for implementations.

To improve consistency across implementations, tighten the specification to include recommended function names. For example:

• a method to convert a latitude and longitude into a 10 digit Open Location Code
  • Consider to name this function xxxYyyyZzzzz or XXX_YYY_ZZZZ

Yes, this assumes people are using object oriented languages. I understand that not everybody uses object oriented languages and they will need to consider longer function names. Also, I am left-handed and I know that when I approach a pair of scissors that they are designed for the rest of the world and not me.

[bocops]

Isn't this mostly covered by API.txt already?

[fulldecent]

Yes. That file is normative and it should be merged into the specification file.

Or at a minimum it needs to be linked.

---

---

P.S. Here is an example of a specification that is expressed in a slightly informal way: https://eips.ethereum.org/EIPS/eip-721

I came to the Open Location Code project repository expecting to find at least this level of formalism in its specification.

I am able to contribute a specification of this calibre here and also update the project to be self-consistent across all the languages. I'm checking with my clients to see who can sponsor my work on this. And also I'm testing the waters here to see what appetite you have for accepting changes in this project. :-p

[fulldecent]

Recommended tag: specification

[fulldecent]

Also, the specification in https://github.com/google/open-location-code/blob/master/API.txt conflicts with the specification at https://github.com/google/open-location-code/blob/master/docs/specification.md

The former states that every function "should" be implemented and the latter states that some "must" and others "should" be implemented.

I am considering that these words are being used as defined in RFC 2119. And therefore those statements are incompatible.

---

I have a proposed specification that fixes this and other issues. PR coming.

[fulldecent]

This is fixed at #463

All normative notes about function names are moved into the new Open Location Code API Specification.