Naming conventions

Соглашения об именовании (naming conventions) играют важную роль в разработке приложений на базе Mapbox GL JS. Библиотека содержит большое количество объектов, конфигураций, слоёв, источников данных, событий и пользовательских сущностей. Единообразный подход к именованию упрощает поддержку проекта, облегчает навигацию по коду и снижает вероятность ошибок при работе с картографическими компонентами.

Стиль именования в API Mapbox GL JS

Mapbox GL JS придерживается общепринятых соглашений JavaScript.

PascalCase для классов

Все конструкторы и классы используют стиль PascalCase.

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v12'
});

const marker = new mapboxgl.Marker();

const popup = new mapboxgl.Popup();

Примеры классов:

mapboxgl.Map
mapboxgl.Marker
mapboxgl.Popup
mapboxgl.NavigationControl
mapboxgl.GeolocateControl
mapboxgl.LngLat
mapboxgl.LngLatBounds

Особенность PascalCase заключается в том, что каждое слово начинается с заглавной буквы.

Map
Marker
Popup
NavigationControl
GeolocateControl

camelCase для методов

Методы экземпляров используют стиль camelCase.

map.addLayer();
map.addSource();
map.getZoom();
map.getCenter();
map.flyTo();
map.fitBounds();

Примеры:

map.addControl(control);
map.removeLayer('buildings');
map.setCenter([30, 60]);
map.getStyle();

Характерные признаки:

первое слово начинается со строчной буквы;
каждое следующее слово начинается с заглавной буквы;
пробелы отсутствуют.

addLayer
addSource
removeSource
getCenter
getBounds
flyTo
queryRenderedFeatures

camelCase для свойств объектов

Большинство свойств конфигурационных объектов также используют camelCase.

map.flyTo({
    center: [37.6176, 55.7558],
    zoom: 12,
    essential: true
});

Другие примеры:

{
    dragRotate: false,
    attributionControl: true,
    renderWorldCopies: false
}

Именование переменных карты

Краткое имя map

Экземпляр карты традиционно называется map.

const map = new mapboxgl.Map({...});

Такое имя является фактическим стандартом во всех примерах документации.

Несколько карт

Если приложение содержит несколько карт, используются более конкретные названия.

const cityMap = new mapboxgl.Map({...});
const overviewMap = new mapboxgl.Map({...});
const satelliteMap = new mapboxgl.Map({...});

Плохой вариант:

const map1 = new mapboxgl.Map({...});
const map2 = new mapboxgl.Map({...});

Хороший вариант:

const primaryMap = new mapboxgl.Map({...});
const secondaryMap = new mapboxgl.Map({...});

Именование источников данных

Источник данных (source) является фундаментальным элементом Mapbox GL JS.

Добавление источника:

map.addSource('cities', {
    type: 'geojson',
    data: citiesData
});

Имя источника должно отражать содержимое данных.

Хорошие примеры

'cities'
'roads'
'countries'
'weather'
'earthquakes'
'bike-routes'
'railway-stations'

Плохие примеры

'data'
'layer1'
'source123'
'test'
'temp'

Использование префиксов

В крупных проектах полезно группировать источники по типу.

'vector-roads'
'vector-buildings'

'geojson-cities'
'geojson-parks'

'raster-satellite'
'raster-weather'

Такой подход облегчает понимание структуры проекта.

Именование слоёв

Каждый слой имеет уникальный идентификатор.

map.addLayer({
    id: 'city-labels',
    type: 'symbol',
    source: 'cities'
});

Название слоя должно описывать:

данные;
тип визуализации;
назначение.

Слои точек

'cities'
'city-points'
'capital-points'
'airports'
'station-markers'

Слои линий

'roads'
'highways'
'railways'
'bike-routes'
'river-lines'

Полигональные слои

'countries'
'regions'
'parks'
'lakes'
'building-footprints'

Слои подписей

Подписи рекомендуется выделять отдельно.

'city-labels'
'road-labels'
'country-labels'
'park-labels'

Часто используется суффикс:

-labels

Слои подсветки

Для временного выделения объектов удобно использовать специальные суффиксы.

'selected-feature'
'hover-highlight'
'active-region'

или

'roads-highlight'
'cities-selected'
'parks-hover'

Соглашения для событий

События в Mapbox GL JS представлены строковыми литералами.

Примеры встроенных событий:

map.on('load', handler);
map.on('click', handler);
map.on('move', handler);
map.on('zoom', handler);

Названия встроенных событий всегда записываются в нижнем регистре.

load
click
mousemove
mouseenter
mouseleave
zoom
moveend

Именование обработчиков событий

Обработчики рекомендуется называть по шаблону:

handle + Событие

Пример:

function handleMapClick(event) {
    console.log(event.lngLat);
}

map.on('click', handleMapClick);

Другие варианты:

function handleZoomEnd() {}
function handleMouseMove() {}
function handleLayerHover() {}

Использование префикса on

Распространён альтернативный стиль.

function onMapLoad() {}

function onMapClick() {}

function onZoomChange() {}

Пример:

map.on('load', onMapLoad);

Главное требование — единообразие внутри проекта.

Именование маркеров

При работе с несколькими маркерами необходимо использовать предметные имена.

const userMarker = new mapboxgl.Marker();

const officeMarker = new mapboxgl.Marker();

const destinationMarker = new mapboxgl.Marker();

Неудачный вариант:

const marker1 = new mapboxgl.Marker();
const marker2 = new mapboxgl.Marker();

Коллекции маркеров

Массивы рекомендуется называть во множественном числе.

const cityMarkers = [];

const restaurantMarkers = [];

const weatherStations = [];

Именование всплывающих окон

Для объектов Popup применяются имена с суффиксом Popup.

const cityPopup = new mapboxgl.Popup();

const airportPopup = new mapboxgl.Popup();

const informationPopup = new mapboxgl.Popup();

Такой подход позволяет мгновенно определить тип объекта.

Именование координат

Mapbox GL JS использует географические координаты в формате longitude/latitude.

Стандартные названия

const longitude = 37.6176;
const latitude = 55.7558;

Сокращённые варианты:

const lng = 37.6176;
const lat = 55.7558;

Именно эти сокращения используются внутри API библиотеки.

event.lngLat

Объекты координат

const cityCenter = {
    lng: 37.6176,
    lat: 55.7558
};

или

const mapCenter = [37.6176, 55.7558];

Именование GeoJSON-данных

Название переменной должно отражать содержимое.

const citiesGeoJSON = {...};

const roadsGeoJSON = {...};

const buildingsGeoJSON = {...};

Если данные поступают с сервера:

const fetchedCitiesGeoJSON = {...};

const remoteRoadsGeoJSON = {...};

FeatureCollection

const cityFeatures = {
    type: 'FeatureCollection',
    features: [...]
};

Для коллекций полезно использовать суффикс:

Features

или

FeatureCollection

Именование пользовательских слоёв

В больших проектах количество слоёв может исчисляться десятками или сотнями.

Полезно придерживаться структуры:

категория-подкатегория-тип

Примеры:

transport-roads-line
transport-railways-line
transport-airports-symbol

admin-countries-fill
admin-countries-border
admin-cities-label

nature-rivers-line
nature-lakes-fill
nature-forests-fill

Преимущества:

логическая группировка;
удобный поиск;
простая фильтрация;
предсказуемая структура.

Именование пользовательских контролов

Для собственных контролов используется PascalCase.

class SearchControl {
}

class LayerSwitcherControl {
}

class WeatherControl {
}

Экземпляры создаются через camelCase.

const searchControl = new SearchControl();

const weatherControl = new WeatherControl();

Именование пользовательских классов карты

Если приложение содержит специализированные обёртки над Mapbox GL JS, рекомендуется указывать предметную область в названии.

class CityMap {
}

class LogisticsMap {
}

class NavigationMap {
}

Менее информативный вариант:

class MapManager {
}

Более информативный вариант:

class DeliveryMapManager {
}

class FleetMapManager {
}

Именование асинхронных функций

Асинхронные операции желательно отражать в имени функции.

async function loadCities() {
}

async function fetchRoadNetwork() {
}

async function loadWeatherData() {
}

Распространённые префиксы:

load
fetch
request
retrieve

Примеры:

fetchGeoJSON()
loadMapStyle()
requestTrafficData()

Именование констант

Константы обычно оформляются в стиле UPPER_SNAKE_CASE.

const DEFAULT_ZOOM = 10;

const MAX_ALLOWED_ZOOM = 18;

const EARTH_RADIUS_METERS = 6378137;

Для настроек карты:

const DEFAULT_CENTER = [37.6176, 55.7558];

const DEFAULT_STYLE =
    'mapbox://styles/mapbox/streets-v12';

Именование файлов проекта

Типичная структура:

map.js
map-init.js
map-events.js
map-controls.js

sources.js
layers.js
markers.js

geojson-loader.js
style-manager.js

Для React-проектов:

MapView.jsx
MapContainer.jsx
LayerManager.jsx
MarkerManager.jsx

Naming conventions

Стиль именования в API Mapbox GL JS

PascalCase для классов

camelCase для методов

camelCase для свойств объектов

Именование переменных карты

Краткое имя map

Несколько карт

Именование источников данных

Хорошие примеры

Плохие примеры

Использование префиксов

Именование слоёв

Слои точек

Слои линий

Полигональные слои

Слои подписей

Слои подсветки

Соглашения для событий

Именование обработчиков событий

Использование префикса on

Именование маркеров

Коллекции маркеров

Именование всплывающих окон

Именование координат

Стандартные названия

Объекты координат

Именование GeoJSON-данных

FeatureCollection

Именование пользовательских слоёв

Именование пользовательских контролов

Именование пользовательских классов карты

Именование асинхронных функций

Именование констант

Именование файлов проекта

Рекомендуемая схема именования в крупном проекте

Источники

Слои

Переменные

Обработчики

Пользовательские классы