Хорошее именование - одна из самых сложных задач при разработке программного обеспечения, но очень важно не вносить в код дерьмовое именование. Дерьмовые имена для переменных, методов, классов и прочего приводят к ухудшению абстракции, удобочитаемости и расширяемости нашего кода.
Я обобщил 4 простых правила, которые помогут вам улучшить именование в любой части кода. Конечно, таких правил может быть намного больше, и эти 4 - всего лишь мое общее представление именования в реальном мире. Почти все они напрямую связаны с вашими навыками именования разработчика. Я не буду добавлять хорошие примеры именования, потому что есть масса хороших примеров именования и лучше избегать плохих :)
За вами будут ухаживать ваши коллеги, и ваша база кода будет беспорядочной, если вы еще не соблюдаете эти правила.
Правило 1. Именование должно соответствовать контексту
По сути, это означает, что весь код вокруг целевого должен помочь вам назвать то, что вы собираетесь называть. Очень важно помнить, что у вас может быть разная логика (например, представление, бизнес, хранение) и что в именовании должны содержаться только термины из соответствующей логической терминологии.
Contextually bad naming examples: // 1. Trying to add business related names into storage logic const users = db.getAll(); const activeUsers = users.find(user => user.lastLogin > Date.now()); // In this example we added business logic / names (term 'active' includes rule for lastLogin date). This situation still might be valid for some analytics, in terms of repository it will be a mistake. // 2. Trying to add storage / transport names into business logic const activeUsers = [...]; const updatedEntities = db.update(activeUsers); const graphqlModel = activeUsers.map(...); // In term of naming, you are introducing storage name 'entity', transport 'graphql'
Причина этого правила в том, что легче поддерживать код, который имеет один контекст, а не несколько. Речь идет по-прежнему о слоях, о разделении кода, но все это упускает из виду контекст как пластилин для ваших операторов и операторов.
Правило 2. Нейминг должен быть чистым с ведома разработчика.
Код не должен содержать каких-либо имен, которые представляют какие-либо знания разработчика о коде. Звучит странно, но в целом речь идет об именовании библиотек / инструментов / технологий / сервисов в вашем коде. Или например о процессе разработки.
Developers knowledge examples:
// 1. Trying to add knowledge about some storage in business logic
const redis = new RedisClient();
const sessionsFromRedis = redis.get(...);
// Here we are binded to redis. You can not guess what else is in there, why it is used here etc. Much better to have SessionStorage or other wrapper for it.
// 2. Trying to add knowledge about some service outside appropriate wrappers
const b2cToken = b2c.get();
const sfResponse = rp.post(SERVICE_URL);
// Same stuff here. Even if you know what it means, it still add ambiguity, hidden meanings
// 3. Trying to add knowledge about code implementation
throw NotImplementedError(); // Better have NotSupportedError
function sendEmail(params){} // F**K params
Для этого есть много причин - лучшая читабельность / расширяемость и абстракция.
Кто-то скажет, что это правило дерьмо из-за чрезмерного обобщения - у меня есть неоспоримый аргумент для этих ребят. Такие имена скрывают истинное предназначение кода и не отражают его функциональность.
Правило 3. Именование должно отражать сущность объекта.
Имя должно отражать природу объекта и не должно изменяться в течение жизненного цикла объекта.
Проще говоря - не меняйте природу объекта своим именованием. Даже если это приводит к длинным именам, лучше иметь длинные имена, а не путать названия.
Bad change of object nature examples: const allUsers = [...]; const targetPerson = allUsers.find(...); const topCustomer = allUsers.find(...); const searchFilter = allUsers[0].status; // This one not obvious - you have made the firstUserStatus to look like filter.
Причина в том, что код действительно отражает реальность. Я считаю, что у всех вас была ситуация, когда вы думали, что эта переменная содержит определенные значения, но при отладке вы понимаете, что это не так. Или вы думали, что функция «prepareFields» делает одно, а на самом деле - другое.
Иногда вы можете неосознанно нарушать это правило, и это нормально, потому что мы можем не знать природы объекта и предполагать некоторую природу для него, позже мы обнаружим больше и можем изменить ее.
Но в большинстве случаев мы пытаемся синхронизировать именование с нашим собственным мышлением, которое происходит быстро и не подвержено ошибкам. В этом случае мы можем придумать что-то вроде input, prepareData, transformedFields, fields и другие дерьмовые имена, которые люди не поймут и которые мы скоро забудем.
Правило 4. Название должно быть последовательным и условным.
Вам нужна конвенция. Период.
Я имею в виду не соглашение для случая верблюда / паскаль, табуляции / пробелы, это соглашение, которое у вас уже должно быть;) Я имею в виду соглашение, которое обеспечивает семантическое именование. Чтобы получить действительно сырой пример:
- Вы должны называть методы / функции, начиная с глаголов;
- Логическое значение должно начинаться с is / allow и не должно быть отрицательным;
- Переменные должны быть названы с использованием существительных и прилагательных;
- На уровне представления мы можем использовать следующие префиксы / постфиксы (контроллер, сопоставитель, база, запрос, ответ и т. Д.);
- На бизнес-уровне мы должны использовать следующие префиксы / постфиксы (Стратегия, Завод, Сервис и т. Д.);
- Используйте полное имя объекта, если в контексте кода возможна какая-то двусмысленность;
Идея состоит в том, чтобы называть одни и те же вещи одними и теми же именами и не придумывать нетрадиционные наименования. Такой подход позволяет каждому в команде понять ваши намерения и быстро выявлять проблемы, если они есть. Он также решает массу проблем при проверке кода, расширении и изменении кода.
Резюме
Многие разработчики программного обеспечения уже знают все эти правила или считают, что знают их. К сожалению, большинство из нас забывает использовать их в реальной жизни, поэтому я надеюсь, что эта статья станет небольшим напоминанием и руководством для таких людей.
Многие из описанных проблем являются обычными. Так что просто соберите свою команду, придумайте свое собственное соглашение и следуйте ему - после пары итераций вам не нужно будет его менять, и все будут счастливы, что он у вас есть. Нет сомнений в том, что большинство вещей в таких соглашениях можно и нужно автоматизировать с помощью линтеров, расширений IDE или других инструментов.
Спасибо за Ваше внимание!
P.S. Эта статья может быть расширена позже, поэтому, если у вас есть какие-либо предложения или какие-либо полезные советы / правила по именованию - напишите их в комментариях.
P.S. Некоторые полезные ссылки:
Менее абстрактная статья по теме - https://medium.com/better-programming/useful-tips-for-naming-your-variables-8139cc8d44b5
