Improvement: A naming scheme that separates key GIS concerns

[brentforder]

Motivation

Naming is an important factor in designing for the SOLID principle of single-responsibility to produce readable & maintainable code, and to reduce the need for documentation. GIS best-practices also emphasize clear naming to assist developers newer to GIS or those transitioning from other GIS libraries.

MLRN is not a huge library by any means, but in my year of integrating MLRN in my app, at times I struggled to keep track of the tools available in the toolkit because of vague names like OfflineManager and ShapeSource. I've seen others raising issues rooted in misunderstanding the purposes of such implementations. I also believe that a clearer naming scheme will help with maintaining MLRN in the long-term.

I'd like to suggest that MLRN (and it's upstream libraries) move to a naming scheme that distinguishes the key GIS concerns of:

1. Map tiles (AKA "base maps")
2. Map features
3. Map feature annotations

Example renaming for implementations focused on tiles:

Existing Name	Proposed Name
OfflineManager	OfflineTilePackManager
SnapshotManager	TileSnapshotManager
VectorSource	VectorTileSource
RasterSource	RasterTileSource

Example renaming for implementations focused on features:

Existing Name	Proposed Name
ShapeSource	FeatureSource
SymbolLayer	FeatureSymbolLayer
Annotation	AnimatedFeatureAnnotation
PointAnnotation	DraggableFeatureAnnotation
MarkerView	InteractiveFeatureAnnotation
Callout	FeatureAnnotationCallout
CircleLayer	CircleFeatureLayer
FillLayer	FillFeatureLayer
FillExtrusionLayer	ExtrusionFeatureLayer
Light	ExtrusionFeatureLight
HeatmapLayer	FeatureHeatmapLayer
LineLayer	LineFeatureLayer

Example descriptive renaming for misc implementations:

Existing Name	Proposed Name
ImageSource	GeoreferencedImageSource
Images	RasterImageSource
BackgroundLayer	AbstractBackgroundLayer
RasterLayer	AbstractRasterLayer
HeadingIndicator	MovementHeadingIndicator
UserLocation	DeviceLocationIndicator
NativeUserLocation	NativeDeviceLocationIndicator

What do you think?

[KiwiKilian]

Thank you for sharing your idea and taking the time to clearly elaborate, what you are trying to achieve. Highly appreciate it!

Here is my personal view on this topic. As we all now, "naming things" is one of the hardest parts of computer science. For sure there are guard rails, to properly name things, but it's not exactly black or white, right or wrong.

Involved Parties

MapLibre React Native is at a very difficult cross road of these other libraries/topics (possibly incomplete):

• MapLibre Native
• MapLibre GL JS
• MapLibre Style Spec
• The Mapbox counter-parts of these MapLibre Forks
• GeoJSON
• React Native

We have to bring all these together and make a unified interface, which works in React Native for developers consuming this library. We also need make the right choices from mapping functionalities from MapLibre Native to React Native, so all contributors can understand which parts map to what on the other side.

Which way do we want to go?

As some of you may noticed, I've moved stuff around internally a lot the last months, to ease maintenance. I'm also not happy with some naming schemes.

But I would like to steer those names in different direction. Let me make some examples:

• OfflineManager and SnapshotManager both don't only concern the tiles, but also the style is involved, so adding Tiles to their names musn't be more exact then their previous names
• Naming everything a Feature might be confusing to those wanting to use GeometryCollection or Geometry
• UserLocation is not only the Puck, but can also be used without beeing visible, so it's not in all cases a "indicator"
• Everything else regards Sources and Layers, which I will elaborate later on
• Proposed names are quite verbose and might also be confusing to some

In the mix of the named packages, we are the smallest puzzle piece. So we shouldn't try to introduce new naming schemes and rather reuse what's already there. Getting all those upstreams to use the same namings is somewhere close to impossible, it should still be possible to switch from Mapbox to MapLibre without starting from scratch.

Let me explain one problem, where this library works specifically different then the rest of the ecosystem, which wouldn't be necessary. The style spec uses kebab-case instead of camelCase see mapbox/mapbox-gl-style-spec#638. But changing this breaks so much stuff, that's just not feasible to do mapbox/mapbox-gl-js#6584 (comment). Therefore I dislike, that this library introduced a a new way of writing styles and want to change this at some point to be compatible with the style spec. This would allow to pasting styles from mapStyle to Layer style and vice versa. We should also separate between paint and layout properties, as the style spec does. Just noting this, to make my point of unity with the MapLibre space.

This example shows, it's not easy to change everything upstream. And I also dislike this library to have another way of doing things, then everyone else.

My Proposal

As previously noted, our biggest criteria for how we name stuff should be (in this order):

1. Developer experience for library consumers
2. Developer experience for contributors

Right now the components of this library tend to be named more aligned to how their counterparts in MapLibre Native are named. For me this seems to be more contributor centric, then consuming developers. My assumption is, that most MapLibre React Native consumers don't care to much about the native specifics, like a how a public component is mapped to native internals. They rather know MapLibre on the web and questions in this repository are often: "How to do this, like in maplibre-gl-js?". Therefore I want the naming of this library to lean more towards the web parts of MapLibre, which means MapLibre GL JS and the style spec.

In fact there is a great React library for maplibre-gl-js: https://github.com/visgl/react-maplibre. Note this was recently separated from https://github.com/visgl/react-map-gl which has quite a significant amount of stars. I want MapLibre React Native to be somewhat interchangeable with @visgl/react-maplibre, at least in some main design choices. Most importantly there is only one Source and Layer component with a type prop. This maps directly to maplibre-gl-js and the style spec, which makes it a great design choice. It's easy for anyone who knows a style json or addSource and addLayer of maplibre-gl-js to convert this towards @visgl/react-maplibre. Secondly we could think about migrating the Camera and MapView components into oneMap component.

Important

Don't expect this to equal web support. Moving in this direction would make this much easier, as we could just integrate with @visgl/react-maplibre. BUT there is no timeline or guarantee, if there will ever be support for web from MapLibre React Native.

Concerning newcomers to GIS

I didn't go into much detail on this concern yet:

MLRN is not a huge library by any means, but in my year of integrating MLRN in my app, at times I struggled to keep track of the tools available in the toolkit because of vague names like OfflineManager and ShapeSource. I've seen others raising issues rooted in misunderstanding the purposes of such implementations. I also believe that a clearer naming scheme will help with maintaining MLRN in the long-term.

While I understand you intent on naming the components clearer, it also makes it quite verbose. And as previously state, I would avoid creating new terms which aren't use from other MapLibre libs. I think this could also be solved with better documentation. Like having the examples on a website, which would only need some text explaining what each example is trying to solve. This would make the examples also visible to search engines, which we are lacking in our current state. If we ever get web support, many of them could have a web preview. And in general, if this library get more traction, by just working great, we might also get more content around it, explaining how to apply it. Reducing documentation sounds nice as it would lower maintenance. But there is a sweet spot of the amount of docs a library need, so consumers can see what's possible or how the can achieve what the want to solve, and maintaining that documentation.

tl;dr

I don't want to create a completely new interface and introduce names, which aren't yet much used within other MapLibre domains. I rather would like to unify all Sources and Layers to two components: Source and Layer which leverage a type prop. Other parts are named mediocre/fine from my point of view.