Басни на ночь — Хорошие имена как залог успеха

Доброго времени суток всем.

«Как лодку назовешь, так она и поплывет» — довольная известная фраза, которая вполне подходит к функциям, переменным, классам.

Сколько раз вам приходилось читать чужой (а бывает и свой код, каюсь, бывало подобное с моим же кодом) и разбираться с написанным месивом. Назначение переменных, функций, а то и вовсе классов не являются интуитивно понятным.
Казалось бы, есть переменная, есть ее имя, но ее назначение не понятно.

Например

enum Dates{
  GET_FIRST,
  GET_SECOND,
  GET_BOTH,
  None
}

Вот и думай, что этот енам делает эдакого в вашем коде. Вроде из названия перечисления понятно, что дело связано с датами. Может методу передаются две даты, и нужно выбрать какую то из них. А может в расчет нужно брать только определенные даты, первую и вторую из списка. А может что еще, может быть много мнений.
В этом случае ищем место, где этот код используется

Boolean IsInRange(DateTime date1, DateTime date2, Dates pDates) {
  if (pDates==Dates.GET_BOTH) {
    return date1 <= myDate && myDate <= date2;
  }
  if(pDates==Dates.GET_FIRST) {
    return date1 <= myDate && myDate <= date2;
  }
  if(pDates==Dates.GET_SECOND) {
    return date1 < myDate && myDate <= date2;
  }
  return date1 < myDate && myDate < date2;
}

И только тогда можно понять, что енам определяет, брать ли левые и правые границы в расчет.
Но если, для понимания смысла объекта, вы начинаете вникать в код, где он используется, значит название не отражает сути назначения. Это плохое имя.
Можно было бы назвать проще:

enum DateIntervals{
  Open,
  Closed,
  OpenLeft,
  OpenRight
}


В этом случае вряд ли придется лазить по коду, отыскивая места использования енама — его имя и так говорит о своей природе.

Комментарии.
Комментарии — это признак того, что имя не отражает суть. Скорее всего, следует поразмыслить над именем функции, нежели над хорошим комментарием.
Помнится был у меня бзик, писать комментарии ко всему и вся — было лениво, но я старался. Даже там где было понятно. Но по большей части это не приносило пользы, а вот эээ, гемороя — о дааа. Так что, пишите хорошие названия — это реально экономит время. Совершенству нет предела. Бывает по 5 раз переименовываешь, пока не скажешь — «вот, это оно»

Произносимые имена.

• GetPCF
• GetYYYY
• GetNN

Произношение не ахти у этих имен. А вот суть и подавно. Второе имя можно произносить как — ГетУайУайУайУай. — Звучит как, Боже, почему, ну почему…
А если коллега спрашивает, какая функция отвечает за ту или иную операцию, произношение будет не совсем понятным, к тому же не совсем понятно — как же она пишется в итоге.

Префиксы
Во времена отсутствия мощных сред разработок (все относительно конечно), были приняты префиксы.

имена переменных в начале должны содержать префикс, который соответствует определенному типу данных и записывается маленькими буквами. Само имя начинается с большой буквы.
Префикс Тип данных

• a массив (array)
• b BOOL булево целое (один байт)
• by BYTE беззнаковое целое
• c символ (один байт)
• C класс
• d число с двойной точностью (double)
• ....

Даже сейчас встречается подобное. Не стоит этим баловаться. Лучше назовите логично переменную, нежели таскать префиксы.

Насколько длинное должно быть имя?
Если блок использования переменной ограничивается 3 строками, то нет особого смысла называть переменную как firstIndexInUserCollection. Длина имени прямо пропорциональна длине блока. Чем больше блок, тем больше имя.

Имена функций
Публичные функции как правило должны иметь короткое лаконичное имя (в идеале конечно). Иначе каждое обращение извне будет весьма увесистым. Закрытые функции, наоборот, можно сопроводить длинным именем, которое опишет цель ее назначение.

Резюмируя:

• Используете имена, которые выражают ваше намерение. Тогда это сэкономит много времени.
• Следите за комментариями, как правило это признак необходимости небольшого рефакторинга.
• Имя должно быть легко произносимым.
• Не вставляйте суффиксы и префиксы понятные только вам.
• Для функций используйте имена образованные из глагола + существительное/прилагательное
• Избегайте дезинформации — функция должна делать то, что исходит из ее названия, иначе это превращается в постоянное воспоминание того, что же делает функция.
• Базовые классы должны иметь короткие имена. Каждый наследник как правило добавляет по слову. А наследники наследников еще. Вот и может получится длинный паравоз

Happy codding.

Автор: cyberdream