Должны ли имена методов быть легко запоминающимися?
Существуют ли официальные рекомендации C ++, касающиеся количества информации, которая должна быть раскрыта в имени метода? Я спрашиваю, потому что я могу найти множество ссылок в Интернете, но ни одна, которая действительно не объясняет это.
Я работаю над классом C ++ с методом под названием calculateIBANAndBICAndSaveRecordChainIfChanged, что довольно хорошо объясняет, что делает метод. Более короткое имя было бы легче запомнить и не нуждалось в интеллигентности или копировании & вставить для ввода. Это было бы менее наглядно, правда, но функциональность должна быть документирована.
Решение
calculateIBANAndBICAndSaveRecordChainIfChanged считается плохим именем функции, оно нарушает правило «одна функция делает одну вещь».
Уменьшить сложность
Единственная самая важная причина для создания рутины состоит в том, чтобы уменьшить сложность программы. Создайте подпрограмму, чтобы скрыть информацию, чтобы вам не приходилось об этом думать. Конечно, вы должны подумать об этом, когда будете писать рутину. Но после того, как оно написано, вы сможете забыть детали и использовать процедуру, не зная, как она работает. Другие причины для создания подпрограмм — минимизация размера кода, повышение удобства сопровождения и повышение корректности — также являются вескими причинами, но без абстрагирующей силы подпрограмм управление интеллектуальными сложными программами было бы невозможным.
Вы можете просто разбить эту функцию на следующие функции:
CalculateIBAN
CalculateBIC
SaveRecordChain
IsRecordChainChanged
Чтобы назвать процедуру, используйте сильный глагол, за которым следует объект
Процедура с функциональной связью обычно выполняет операцию над объектом. Имя должно отражать то, что делает процедура, а операция над объектом подразумевает имя глагол-плюс-объект. PrintDocument (), CalcMonthlyRevenues (), CheckOrderlnfo () и RepaginateDocument () являются примерами хороших имен процедур.
Опишите все, что делает рутина
В названии подпрограммы опишите все результаты и побочные эффекты. Если подпрограмма вычисляет итоги отчета и открывает выходной файл, ComputeReportTotals () не является подходящим именем для подпрограммы. ComputeReportTotalsAndOpen-OutputFile () — подходящее имя, но оно слишком длинное и глупое. Если у вас есть подпрограммы с побочными эффектами, у вас будет много длинных глупых имен. Лечение не состоит в том, чтобы использовать менее описательные имена рутины; лекарство должно программировать так, чтобы вы заставляли вещи происходить напрямую, а не с побочными эффектами.
Избегайте бессмысленных, расплывчатых или слабых глаголов
Некоторые глаголы эластичны, растянуты, чтобы охватить практически любое значение. Имена подпрограмм, такие как HandleCalculation (), PerformServices (), OutputUser (), ProcessInput () и DealWithOutput (), не сообщают вам, что делают подпрограммы. Самое большее, эти имена говорят вам, что подпрограммы как-то связаны с вычислениями, услугами, пользователями, вводом и выводом. Исключение составляет случай, когда глагол «ручка» используется в особом техническом смысле обработки события.
Большинство из вышеперечисленных пунктов относятся от Код завершен II. Другие хорошие книги Clean Code, The Clean Coder от Роберт С. Мартин
Другие решения
Чтобы ответить на прямой вопрос, я не думаю, что имена функций необходимость быть запоминающимся Хорошо, если они есть, но, как вы говорите, этот материал должен быть задокументирован. Я могу посмотреть это.
calculateIBANAndBICAndSaveRecordChainIfChanged это слишком долго, на мой вкус. Помимо неудобства необходимости использования c / p или автозаполнения, чтобы даже использовать их, я боюсь, что длинные имена функций также не читаются должным образом, поэтому имена с похожими «формами» начинают выглядеть похожими на одно и то же. другой.
Поэтому я бы посоветовал искать более короткое имя. Должна быть некоторая причина, почему эти операции (вычисление двух вещей и условное сохранение цепочки записей) были сгруппированы вместе. Эта причина не описана в вопросе, она лежит где-то в спецификации или истории вашего проекта. Вы должны определить эту причину и найти более краткое имя функции.
При именовании функции вы также можете учитывать, по каким причинам [*] функция может измениться в будущем. Почему две вещи (IBANA и BIC) рассчитываются одновременно? Какая связь между ними? Можете ли вы определить причину, по которой вы делаете это одновременно, а затем экономите?
Например: они являются «аббревиатурами» для этого объекта, обычно требуется пересчитать все аббревиатуры одновременно, и если вы пересчитаете, то, естественно, изменения нужно сохранить. Затем вызовите функцию refreshAcronyms, Возможно, в будущем появится третья аббревиатура.
Другой пример: вызывающие действительно хотят сохранить объект, если он был изменен, и это дополнительная рутинная работа, чтобы сохранить целостность хранимых данных, я должен всегда пересчитать IBANA и BIC перед сохранением. В этом случае все остальное является необходимым прекурсором для сохранения, поэтому я могу вызвать функцию saveRecordChain, Пользователям открытого интерфейса просто нужно знать, что функция сохранения делает то, что нужно сделать. Там может быть serializeToFile() функция в частном интерфейсе, которая сохраняет, если изменилось, не делая лишних вещей.
В идеале один метод должен делать только одно. И имя вашего метода должно отражать то, что он делает (это одно), тогда только ваша программа станет доступной для чтения.
Это вопрос личных предпочтений, хотя я думаю, что calculateIBANAndBICAndSaveRecordChainIfChanged слишком длинный и поэтому трудный для чтения и кодирования (если вы не используете интеллектуальный редактор, который может автоматически заполняться)
Еще два момента:
- Функция должна быть разбита на более мелкие части, как и другие
плакаты предложили. - Там нет закона против комментирования ваших заголовков, чтобы дать больше
подробное описание функции там, так что вам не нужно
встроить каждый аспект его функциональности в имя.
Вы читаете и пишете слишком много методов в течение своей карьеры, чтобы помнить их имена. Большинству программистов нужно искать имя функции в стандартной библиотеке своего языка, не говоря уже об именах функций, разработанных их или их командой! Самое запоминающееся имя функции было бы бесполезно для тех, кто поддерживает ваш код и видит вызов в первый раз. Более того, есть хорошие шансы, что через шесть месяцев вы тоже об этом не вспомните!
Вот почему я рекомендую сначала обратиться к описательным именам, не беспокоясь о легкости запоминания: в конце концов, IDE с intellisense скоро не исчезнут (и были введены по уважительной причине — для решения наших ограничений памяти).
Для личного взаимодействия этого было бы достаточно и полезно, но в любом случае после завершения приложения вы должны переориентировать каждое имя функции в точности на то, что они намерены делать. И если вы работаете в группе или в компании, убедитесь, что имя функции отражает ее функциональность.
И в вашем имени функции, например, я могу назвать его следующим образом: saveRecordWithRespctToIBANandBIC()