Что такое имя функции
Практическое руководство по именованию классов, функций и переменных
В этой статье мы подробно рассказываем о методах именования классов, функций и переменных, которые позволяют улучшить читаемость вашего кода.
«В компьютерном программировании соглашение об именах — набор правил для выбора последовательности символов, которая будет использоваться для идентификаторов, которые обозначают переменные, типы, функции и другие объекты в исходном коде и документации», — «Википедия»
Придумывать названия сложно!
В этой статье мы сосредоточимся на методе именования (P)A/HC/LC для того, чтобы улучшить читаемость кода. Эти рекомендации можно применить к любому языку программирования, в статье для примеров кода используется JavaScript.
Что значит (P)A/HC/LC?
В этой практике используется следующий шаблон для именования функции:
Что обозначает префикс (P)?
Префикс расширяет смысл функции.
Описывает свойство или состояние текущего контекста (обычно — логическое значение).
Указывает, имеет ли текущий контекст определенное значение или состояние (обычно — логическое значение).
Отражает положительный условный оператор (обычно — логическое значение), связанный с определенным действием.
Действие — это сердце функции
Действие — это глагольная часть имени функции. Это самая важная часть в описании того, что делает функция.
Получает доступ к данным немедленно (сокращение от getter для внутренних данных).
Безусловно присваивает переменной со значением A значение B.
Возвращает переменную к её начальному значению или состоянию.
Выполняет запрос данных, для которого требуется время (например, асинхронный запрос).
Удаляет что-то откуда-то.
Полностью стирает что-то. После операции сущность перестаёт существовать.
Создает новые данные из существующих. Обычно это применимо к строкам, объектам или функциям.
Обработка действия. Часто используется при именовании обратного вызова.
Контекст
Контекст — это область, с которой работает функция.
Функция — это часто действие с чем-то. Важно указать, какова её рабочая область или, по крайней мере, ожидаемый тип данных.
В итоге
Пять принципов именования переменных
В этом разделе мы предложим некоторые правила именования переменных, которые улучшат читаемость кода.
1. Следуйте S-I-D
Имя должно быть коротким (Short), интуитивно понятным (Intuitive) и описательным (Descriptive).
2. Избегайте сокращений
Не используйте сокращения. Обычно они только ухудшают читаемость кода. Найти короткое, описательное имя может быть сложно, но сокращения не могут быть оправданием для того, чтобы этого не делать. Например:
3. Избегайте дублирования контекста
Всегда удаляйте контекст из имени, если это не снижает его читабельность.
4. Отражайте в имени ожидаемый результат
5. Учитывайте единственное/множественное число
Как и префикс, имена переменных могут быть единственного или множественного числа в зависимости от того, имеют ли они одно значение или несколько.
Практическое руководство по именованию классов, функций и переменных
В компьютерном программировании соглашение об именах — набор правил для выбора последовательности символов, которая будет использоваться для идентификаторов, которые обозначают переменные, типы, функции и другие объекты в исходном коде и документации, — «Википедия»
Придумывать названия сложно!
В этой статье мы сосредоточимся на методе именования (P)A/HC/LC для того, чтобы улучшить читаемость кода. Эти рекомендации можно применить к любому языку программирования, в статье для примеров кода используется JavaScript.
Что значит (P)A/HC/LC?
В этой практике используется следующий шаблон для именования функции:
Что обозначает префикс (P)?
Префикс расширяет смысл функции.
Описывает свойство или состояние текущего контекста (обычно — логическое значение).
Указывает, имеет ли текущий контекст определенное значение или состояние (обычно — логическое значение).
Отражает положительный условный оператор (обычно — логическое значение), связанный с определенным действием.
Действие — это сердце функции
Действие — это глагольная часть имени функции. Это самая важная часть в описании того, что делает функция.
Получает доступ к данным немедленно (сокращение от getter для внутренних данных).
Безусловно присваивает переменной со значением A значение B.
Возвращает переменную к её начальному значению или состоянию.
Выполняет запрос данных, для которого требуется время (например, асинхронный запрос).
Удаляет что-то откуда-то.
Полностью стирает что-то. После операции сущность перестаёт существовать.
Создает новые данные из существующих. Обычно это применимо к строкам, объектам или функциям.
Обработка действия. Часто используется при именовании обратного вызова.
Контекст
Контекст — это область, с которой работает функция.
Функция — это часто действие с чем-то. Важно указать, какова её рабочая область или, по крайней мере, ожидаемый тип данных.
В итоге
Пять принципов именования переменных
В этом разделе мы предложим некоторые правила именования переменных, которые улучшат читаемость кода.
1. Следуйте S-I-D
Имя должно быть коротким (Short), интуитивно понятным (Intuitive) и описательным (Descriptive).
2. Избегайте сокращений
Не используйте сокращения. Обычно они только ухудшают читаемость кода. Найти короткое, описательное имя может быть сложно, но сокращения не могут быть оправданием для того, чтобы этого не делать. Например:
3. Избегайте дублирования контекста
Всегда удаляйте контекст из имени, если это не снижает его читабельность.
4. Отражайте в имени ожидаемый результат
5. Учитывайте единственное/множественное число
Как и префикс, имена переменных могут быть единственного или множественного числа в зависимости от того, имеют ли они одно значение или несколько.
6. Используйте осмысленные и произносимые имена
Идентификатор или имя функции
Определение функции
Определение функции должно располагаться в глобальной области видимости, до начала функции main. Рассмотрим пример, простого определения:
Определение функции состоит из заголовка и тела. Заголовок фукнции включает в себя:
Тип возвращаемого значения
Почти все функции должны возвращать значения. Тип этого значения указывается в заголовке перед именем функции. Вот несколько примеров заголовков функций:
Идентификатор или имя функции
Список аргументов или параметров
Список аргументов функции записывается в круглых скобках после имени функции. В данном примере список аргументов пуст.
Список аргументов записывается через запятую. Каждый элемент списка состоит из типа и идентификатора. Рассмотрим пример заголовка функции со списком из двух аргументов:
int simple (int a, float b)
В скобках мы записали два аргумента: a и b. У аргумента a тип int, а у аргумента b тип float.
Аргументы используются, когда в функцию нужно передать какие-либо данные из вызывающего окружения.
Тело функции
Тело функции располагается сразу под заголовком и заключено в фигурные скобки. В теле функции может содержаться сколько угодно операторов. Но обязательно должен присутствовать оператор return. Оператор return возвращает значение:
Здесь, simple_function всегда будет возвращать 0. Надо признать, что данная функция бесполезна. Напишем функцию, которая принимает из вызывающего окружения два значения, складывает их и возвращает результат в вызывающее окружение. Назовём эту функцию sum (сумма):
int sum (int a, int b)
В теле функции определяется переменная c. А затем, в эту переменную мы помещаем значение суммы двух параметров.
Последняя строчка возвращает значение переменной c во внешнее окружение.
После ключевого слова return нужно указать значение которое будет возвращено. Можно возвращать как простые значения, так и переменные и даже выражения. Например:
В последнем случае в вызывающее окружение будет возвращён результат суммы переменных a и b.
Обратите внимание, что оператор return не только возвращает значение, но и служит как бы выходом из функции, после него не будет выполнен ни один оператор:
c = a+b; // этот оператор не будет выполнен
Благодаря этому, с помощью return удобно создавать условия выхода из функций:
Имена методов и функций
Изучая всякого рода системы, я обнаружил, что у многих наблюдаются проблемы с именованием методов. Это побудило меня написать статью.
Что побудило меня написать статью?
После того, как я в тысячный раз полез в мануал, чтобы узнать порядок аргументов в PHP-функции str_replace, стало ясно, что проблема весьма актуальна. Ведь имя функции «str_replace» говорит нам только о том, что она делает, но ничего не говорит об аргументах. Чем это чревато? Ладно, можно запомнить число и порядок аргументов во встроенной библиотеке, но в собственной разработке запоминать аргументы не так-то и просто. Да, есть среды разработки, которые нам подсказывают, но они не срабатывают при наведении глаза на функцию, поэтому читать такой код сложно. А ведь важно, чтобы код легко читался и понимался без комментариев. Это признак качественного кода.
В качестве примера многочисленных ошибок, приведу PHP. Сразу могу назвать несколько ошибок:
1. Имена некоторых функций неочевидно передают назначение. Например, basename.
2. Имена функций составлены не по одному принципу. Например, строковые функции начинаются с str_, но не все (например, strstr, strpos). С файлами та же проблема: filesize vs file_exists.
Значит, надо придумывать имена методов/функций так, чтобы:
1. Имя функции/метода четко передавало его назначение.
2. Имена функций/методов составлены по одному принципу/стандарту.
3. Порядок и список аргументов в функциях/методах были составлены по одному принципу и сочетались с именем.
4. Методы оставались методами.
Поясню 4ый пункт. Нередко я встречаю строки вида object.Pi(): такой метод не имеет отношения к объекту. Это скорее функция (или константа).
Примеры и не только
1. Нам нужна замена подстроки в строке. Самым очевидным вариантом будет такой: string.replace(from, to). Жаль, что в PHP он не осуществим.
2. Намекаем на аргументы и смысл: groups.getByName(name). Ничего лишнего. Не надо писать getGroupByName, ведь контекст ясен благодаря groups. Точно так же и другие методы: groups.remove(group) либо group.delete(). Ага! И тут интересный момент 🙂 Если мы удаляем из коллекции, то коллекция.remove(элемент). А если элемент сам удаляет себя, то элемент.delete(). И это важно: наш код должен быть валидным в плане английского языка.
3. Антонимы в именах функций/методов. Да, всегда надо использовать верные антонимы при именовании. Добавляем и удаляем элементы в коллекции: add/remove. Создаем и удаляем объекты: create/delete. Начинаем и завершаем процесс: begin/end, start/finish (но никак не begin/finish и start/end).
Умеете ли вы правильно называть функции?
Авторизуйтесь
Умеете ли вы правильно называть функции?
Автор перевода — Мария Багулина
Названия функций крайне важны, особенно если вы занимаетесь разработкой пользовательского API. Иногда имя может прекрасно описывать то, что делает функция, но на практике оказывается абсолютно бесполезным. И с этим можно столкнуться даже в стандартных библиотеках. В качестве примеров рассмотрим несколько функций C++20.
Пример 1: std::log2p1()
Начнём с функции std::log2p1(). Её код выглядит так:
Функция просто возвращает двоичный логарифм числа плюс один, о чём и говорит её название.
Но какая от этого польза?
На самом деле std::log2p1(x) возвращает количество битов, необходимых для хранения x. Это действительно нужная функция, но её название совсем не отражает суть выполняемой операции.
Пример 2: std::bless()
Если вы плохо знакомы с языком C++, то вот быстрое введение в его объектную модель.
В С++ существует такая штука, как указатель — переменная, в которую записывается адрес другого объекта в памяти. Над указателем можно выполнять арифметические действия, но только если он является элементом массива. Почему так? Потому что нельзя вычитать или прибавлять что-то к произвольному указателю — это не имеет смысла, так как расположение объектов в памяти неизвестно.
Однако такое действие не является явной ошибкой, а порождает неопределённое поведение (то есть результат, зависящий от состояния памяти, компилятора, фазы луны или каких-либо других случайных факторов).
Проблема сводится не к глупым программистам, которые зачем-то складывают указатели (ведь это не запрещено), а к самому языку С++. Поэтому Ричард Смит, исследователь из Google, предложил добавить в стандарт функцию std::bless(void* ptr, std::size_t n), чтобы при необходимости автоматически выделять массив памяти и тем самым разрешить вопрос с арифметикой для указателей.
Имя bless, разумеется, никак не сообщает обо всех этих нововведениях, поэтому было решено придумать другое название для функции. За дело взялся комитет по развитию языка C++: в качестве кандидатов они выдвинули верси и implicitly_create_objects() и implicitly_create_objects_as_needed() («неявно создать объекты» и «неявно создать объекты при необходимости»). Имена вполне логичны, ведь функция делает именно то, что в них сказано. Но, согласитесь, если бы вы не знали предысторию, то совершенно не поняли, зачем нужно создавать какие-то объекты.
Пример 3: std::popcount()
Напоследок ещё одна стандартная функция C++ 20. Просто посмотрите на её имя и попробуйте угадать, что она делает. Кажется, что-то считает? Может быть, это связано со стековыми операциями pop и push?
Скорее всего, вы не догадаетесь, если только уже не знаете о низкоуровневой инструкции с таким же названием. Функция popcount (сокращённо от «population count») подсчитывает количество установленных битов в машинном слове.
С одной стороны, это было бы отличное имя, если бы все разработчики знали названия ассемблерных битовых операций. Но будет ли оно очевидно новичку, который не в курсе таких тонкостей?
Как же следует называть функции?
Ни одно из имён, представленных выше, нельзя назвать плохим: они действительно описывают то, что делают функции. Но для вас, как пользователя, эти имена бесполезны — они содержат не ту информацию, которая вам нужна.
Имена, которые описывают реализацию функции, будут понятны для разработчиков, но могут оказаться совершенно бессмысленными для пользователей. Причём этими пользователями являются другие разработчики, которые хотят подключить к своему проекту кем-то созданную библиотеку. Согласитесь, в этом случае важно то, что делают функции, а не как они реализованы.