пятница, 13 сентября 2013 г.

Как называть переменные и функции: rules of thumb

Меня давно уже волнует вопрос, как нужно называть переменные и функции, чтобы код был понятнее. Понравились следующие мысли по этому вопросу (ниже конспект из книги Р. Мартина "Чистый код. Создание, анализ и рефакторинг"). Выписала оттуда не все советы, а только те, что могут пригодиться в ближайшее время.

1. Имена должны передавать намерения программиста. Имя переменной, функции или класса должно сообщить, почему оно существует, что она делает и как используется. Если имя требует дополнительных комментариев, значит, оно не передает намерений программиста.

Плохо:
int d: //Прошедшее время
Хорошо:
int elapsedTimeInDays;
int daysSinceCreation;
int daysSinceModification;
int fileAgeInDays;

Плохо:
Хорошо:

2. Избегайте дезинформации.

2.1. Переменным не стоит присваивать имена типа hp, aix и sco, потому что они ассоциируются с платформами и разновидностями Unix. Даже если в переменной хранится длина гипотенузы и имя hp кажется хорошим сокращением, оно может ввести в заблуждение читателя кода.

2.2. Не обозначайте группу учетных записей именем accountList,  если только она действительно не хранится в списке. Лучше подойдут такие имена, как accountGroup, bunchOfAccounts или даже просто accounts. 

2.3. Остерегайтесь малозаметных различий в именах. Сколько времени потребуется, чтобы заметить незначительное различие в XYZControllerForEfficientHandlingOfStrings и XYZControllerForEfficientStorageOfStrings?

2.4. Не используйте комбинации из "l" и "O" в именах переменных, потому что они похожи на 0 и 1.

Плохо:
int a = l;
if ( O == l )
    a = ol;
else
    l = ol;

3. Используйте осмысленные различия

Плохо:
Хорошо:
Вместо a1 и a2 лучше использовать source и destination.

Плохо:
-Классы Product, ProductInfo, ProductData  - разные имена, которые по сути обозначают одно и тоже. 
-Методы getActiveAccount(), getActiveAccounts(),  getActiveAccountInfo(). Как понять, какую из этих функций вызывать в конкретном случае?

4. Используйте удобопроизносимые имена.
Если имя невозможно нормально произнести, то при любом его упоминании в обсуждении вы выглядите полным идиотом. "Итак, за этим би-си-эр-три-си-эн-тэ у нас идет пи-эс-зэт-кью, видите?"

5. Однобуквенные имена могут использоваться только для локальных переменных в коротких методах. Длина имени должна соответствовать размеру его области видимости. Однобуквенные переменные хорошо использовать в счетчиках цикла.

6. Имена классов и объектов должны представлять собой существительные и их комбинации: Customer, WikiPage, Account, AddressParser. Старайтесь не использовать в именах классов такие слова, как Manager,  Processor, Data, Info. Имя класса не должно быть глаголом. 

7. Имена методов представляют собой глаголы или глагольные сочетания: postPayment, deletePage, save и т.д. Методы чтения/записи и предикаты образуются из значения и префикса get, set, is.
Хорошо:
string name = employee.getName();
customer.setName("mike");
if (paycheck.isPosted())

8. Выберите одно слово для каждой концепции. Например, существование в разных классах эквивалентных методов с именами fetch, retrieve и get неизбежно создаст путаницу. Аналогичным образом, использование терминов controller, manager и driver в одной кодовой базе тоже вызывает путаницу. Чем DeviceManager принципиально отличается от ProtocolController?

9. Старайтесь не использовать одно слово в двух смыслах. Допустим, программа содержит много классов с методами add, которые создают новое значение сложением или конкатенацией двух существующих значений. Вы пишете новый класс с методом, помещающим свой единственный параметр в коллекцию. Стоит ли присвоить этому методу имя add? Т.к. новый метод имеет другую семантику, то ему лучше присвоить имя insert или append.

10. Не стесняйтесь использовать термины из области информатики, названия алгоритмов и паттернов, математические термины и т.д. Имя AccountVisitor сообщит много полезной информации программисту, знакомому с паттерном "Посетитель". Если для того, что вы делаете, не существует подходящего программизма, используйте имя из пространства задачи. По крайней мере программист, занимающийся сопровождением кода, сможет узнать у специалиста в предметной области, что означает это имя. 

Комментариев нет:

Отправить комментарий