open-location-code icon indicating copy to clipboard operation
open-location-code copied to clipboard

Published 20 hours ago • verified publisher icon google

Specification should recommend function names

Open fulldecent opened this issue 4 years ago • 5 comments

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.

fulldecent avatar Apr 20 '21 16:04 fulldecent

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

bocops avatar Apr 20 '21 19:04 bocops

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 avatar Apr 20 '21 19:04 fulldecent

Recommended tag: specification

fulldecent avatar Apr 25 '21 04:04 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 avatar Apr 26 '21 02:04 fulldecent

This is fixed at https://github.com/google/open-location-code/pull/463

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

fulldecent avatar Jun 04 '21 18:06 fulldecent