search

google / open-location-code

Open Location Code is a library to generate short codes, called "plus codes", that can be used as digital addresses where street addresses don't exist.
https://plus.codes
Apache License 2.0
4.04k stars 465 forks source link

Specification should recommend function names #432

Open fulldecent opened 3 years ago

fulldecent commented 3 years ago

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 commented 3 years ago

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

fulldecent commented 3 years ago

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 commented 3 years ago

Recommended tag: specification

fulldecent commented 3 years ago

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 commented 3 years ago

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.