Pull to refresh

Имена методов и функций

Reading time 3 min
Views 35K
Изучая всякого рода системы, я обнаружил, что у многих наблюдаются проблемы с именованием методов. Это побудило меня написать статью.

странный кусок кода

Что побудило меня написать статью?


После того, как я в тысячный раз полез в мануал, чтобы узнать порядок аргументов в PHP-функции str_replace, стало ясно, что проблема весьма актуальна. Ведь имя функции «str_replace» говорит нам только о том, что она делает, но ничего не говорит об аргументах. Чем это чревато? Ладно, можно запомнить число и порядок аргументов во встроенной библиотеке, но в собственной разработке запоминать аргументы не так-то и просто. Да, есть среды разработки, которые нам подсказывают, но они не срабатывают при наведении глаза на функцию, поэтому читать такой код сложно. А ведь важно, чтобы код легко читался и понимался без комментариев. Это признак качественного кода.

В качестве примера многочисленных ошибок, приведу PHP. Сразу могу назвать несколько ошибок:

1. Имена некоторых функций неочевидно передают назначение. Например, basename.

2. Имена функций составлены не по одному принципу. Например, строковые функции начинаются с str_, но не все (например, strstr, strpos). С файлами та же проблема: filesize vs file_exists.

3. Неочевидность аргументов и их порядка в функциях. Например, искомая строка в функции str_replace идет на последнем месте, а в функции strpos — на первом (str_replace($search, $replace, $subject[, $&count]) vs strpos($haystack, $needle[, $offset])). Если бы искомая строка, например, всегда занимала первую позицию — было бы более удобно.
Да, таково наследство Си (и не только), но неважно: проблема есть проблема.

Ага


Значит, надо придумывать имена методов/функций так, чтобы:

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).

4. Булевые возвращаемые значения. Да-да-да, и на это следует намекнуть, чтобы код легко читался. Такие слова как: has, is, was, have в начале имени метода намекают нам на то, что этот метод возвращает булевое значение. Пример: object.hasData(). Спасибо kroz за напоминание.

5. Намекаем на порядок аргументов в методе: cars.getByMonthAndYear(month, year).

6. Формирование имени. Имя метода — это своеобразное предложение, которое обязательно состоит из сказуемого (input.focus()), но может содержать дополнения (element.appendChild()), определения (window.slowlyShow()) и их комбинации (todo.getNewTask()). Но правило часто нарушается. Например, user.next(). Ага… были похожие ситуации? Эта проблема присуща языкам программирования, в которых нету свойств (property). Да, приходится мириться с такими именами. Плохо это или хорошо — решать вам.

Итого


Надеюсь, эта статья была для вас полезна. Хотите больше? Тогда сходите в книжный магазин и купите книгу Стива Макконнелла «Совершенный Код».
Tags:
Hubs:
+102
Comments 176
Comments Comments 176

Articles