Имя пользователя:

Пароль:


Список форумов ПРАКТИЧЕСКИЕ ВОПРОСЫ Работа Программирование и IT Просмотров: 1172

Элегантное программирование: искусство именования объектов


Давим клаву за бабло
  #1
Сообщение 28 Dec 2013, 10:58
Ursego Аватара пользователя
СОЗДАТЕЛЬ ТЕМЫ
Canada, Ontario
Город: Toronto
Стаж: 11 лет 7 месяцев 5 дней
Постов: 10707
Лайкнули: 3448 раз
Карма: 33%
СССР: Днепропетровск
Пол: М
Лучше обращаться на: ты
Заход: 20 Nov 2023, 18:00

Точное значение

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

Используйте слова "per" и "by" - они реально облегчают жизнь разработчика! Имя переменной cowsPerFarm лучше, чем totalCows, а имя функции RetrieveCityByCountry говорит нам больше, чем RetrieveCity (особенно если нет параметров, несущих дополнительную информацию). Эти короткие, но важные слова ("per" и "by") особенно здорово облегчают написание и чтение финансовых вычислений!

Не используйте абстрактные слова вроде "actual" и "total" - они будут сводить вас с ума заставляя тратить время в попытках понять что значит "actual" (что в таком случае "не actual"), и для какого именно уровня группирования использовано слово "total". Например, totalCows - это к-во коров на ферме? в деревне? в области или штате? в стране? во всей Вселенной? Если, например, на ферме, то как вы назовёте переменную для к-ва коров в деревне? Она ведь тоже "total"! Эти абстрактные слова бессмысленны вне контекста (который был очевиден архитектору данных когда он создавал таблицу), но покрыты туманом позже, когда переменная окружена кодом...

Только точные определения, которые вызовут минимум вопросов, даже если это увеличит длину имён!

*** Не рекомендуется: ***

totalSalary = actualSalary * totalHours;

*** Рекомендуется: ***

salaryPerDay = salaryPerHour * hoursPerDay;


Последовательность

Не создавайте разные версии имени для одной и той-же сущности (как, например, employee_id / employee_no / employee_num / emp_id / emp_no / emp_num).

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

Длинные, описательные имена

Общепринятая практика требует давать переменным и функциям короткие имена. В большинстве случаев это оправдано, но всё-же иногда может возникнуть ситуация, когда имеет смысл отойти от этого правила и использовать длинные имена, напоминающие фразу на нормальном человеческом языке - например, для переменной экземпляра, упоминаемой в коде лишь пару-тройку раз (но никак не для локальной переменной, многократно используемой в коде метода).

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

mainFilter = this.GetMainFilter(); // bad...
filterBySelectedRowInSummaryScreen = this.GetFilterBySelectedRowInSummaryScreen(); // good!

Как видите, имя переменной может рассказать целую историю! Это делает строки кода длинней, но её можно разбить на несколько - это лучше, чем тупо глазеть на переменную не имея никаких предположений что в ней хранится! И всё-же помните: вы - не Лев Толстой :mrgreen: , так что этот совет - не правило, а исключение из него.

Сокращения (аббревиатуры)

Сокращайте слова только если смысл аббревиатуры будет более, чем очевиден.

Пытаясь уменьшить размер кода, мы зачастую сокращаем слова, используемые в именах таблиц, полей, переменных и т.д. Сокращаем иногда слегка, иногда значительно - это обычно зависит от практики, принятой в компании. В одном из проектов мне пришлось изрядно помучиться от очень жёстких правил сокращения - надо было обрубать всё, что попадается на глаза! Нельзя было использовать гласные (кроме начальных, например wrk - work, crtfc - certificate, insr - insurance) и имелся целый свод законов по отделению мяса от костей. В результате получались имена, понятные только древним египтянам - я был счастлив, когда контракт закончился.

В другом проекте была противоположная ситуация - вообще никаких сокращений! ОК, иногда можно (как в случае с "id", "sys", "col" or "num"), но обычно - целые предложения, используемые как имена объектов. Я читал методы классов как приключенческую книгу, а не как код на языке программирования! Сначала пришлось испытать шок: как же так, разве они не знают, что надо стараться сделать код покороче? Но, скажу я вам, работа в этом проекте была удовольствием! Так что попробуйте принять эту необычную и шокирующую, но великую идею: не сокращайте слова совсем!

Конечно, этой идеей могут воспользоваться только те, кто создаёт новые системы (включая объекты базы данных) - если имена уже созданы, надо быть последовательным в использовании того, что есть, и не допускать версий одного и того-же имени.

Сейчас я перечислю 4 случая, когда аббревиатуры должны использоваться (т.е. 4 исключения из описанного правила):

1. Аббревиатуры, широко используемые в данном бизнесе (обычно они прочно входят в язык айтишников этой фирмы и воспринимаются как полноценные слова).

2. Общепринятые аббревиатуры, связанные с языком программирования или технологией разработки. Например, любой кодирующий на C/C++ знает, что "ptr" означает "pointer", а каждый зарабатывающий на хлеб с помощью баз данных не сомневается в значении скоращений "PK" and "FK".

3. Длинные слова или словосочетания, используемые в имени локальной переменной, упоминаемой в коде метода многократно. В этом случае надо добавить комментарий к объявлению переменной, например:

string pcm; // pcm = previous calculation method.

4. Слова из следующего списка (они встречаются в практике часто, во всяком случае в бизнес-программировании, поэтому имеет смысл привыкнуть к сокращениям):

amt - amount
arg - argument
arr - array
asc - ascending
buf - buffer
calc - calculate, calculation
col - column
cnt - count (не counter!)
ctr - counter
cust - customer
curr - current
def - definition
del - delete
desc - descendant (не description!)
descr (dscr) - description
dest - destination
dif - difference
doc - document
elig - eligible, eligibility
emp - employee (не employer!)
env - environment
err - error
exp - expired, expiration (не expression!)
expr - expression
frag - fragment
id - identifier
idx - index
img - image
ind - indicator (не index!)
ini(t) - initial
info - information
ins - insert
inv - invoice (не inventory!)
qty - quantity
len - length
max - maximum
min - minimum
misc - miscellaneous
msg - message (не monosodium glutamate! :mrgreen: )
num - number
obj - object
orig - original
parm - parameter
pos - position
prev - previous
ptr - pointer
ref - reference
res - result
ret - return
rc - return code
sel - select
src - source
srv - service
sum - summary
sys - system
temp - temporary (не temperature!)
upd - update
val - value
win - window

Время действия

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

Давая имена полям таблиц и переменным, не заставляйте читающих код угадывать время, когда действие должно иметь место. Например, в одном из проектов, в которых меня занесло, две разные таблицы в БД имели поле calc_method (метод расчёта), но одно из них хранило последний использованный метод, а второе - метод, который следовало использовать при следующем расчёте. Не понимаю почему было не назвать эти поля соответственно calc_method_used и calc_method_to_use (или last_calc_method и next_calc_method)? Это бы здорово улучшило понимание бизнес-кода и SQL-запросов.

Общий совет: используйте слова do..., ...ToDo, perform..., execute..., ...ToApply и т.д. если действие должно иметь место в будущем и ...Done, ...Performed, ...Executed, ...Occurred, ...Passed, ...Applied и т.п. если действие уже произведено.

Другая грустная история - логические (Boolean) переменные, имена которых состоят из одного существительного (без глагола). Что скажете о булевской переменной isCalculation? Calculation - что??? Как понимать условие if (isCalculation)? Вот назвали бы переменную isCalculationDone (isCalculated) или doCalculation (calculate), и не пришлось бы ломать голову!

  #2     Элегантное программирование: искусство именования объектов
Сообщение 28 Dec 2013, 17:03
Cth Аватара пользователя
Canada, British Columbia
Город: Vancouver
Стаж: 10 лет 3 месяца 5 дней
Постов: 1550
Лайкнули: 312 раз
Карма: 21%
Пол: М
Заход: 09 Aug 2022, 19:36

ну, как бы, все это можно записать в одно правило:

пишите так, чтобы потом смогли понять, что имели ввиду.


тем, кому приходилось много писать, а потом возвращаться к каким-то кусочкам и переделывать их (особенно через год, или пять лет) должны быть эти все правила очевидными. Да что значит писать? Эти правила свободно распостраняются на студентов, которым надобно конспектировать лекции :) точно то же самое. особенно лекции по математическому анализу - там много похожих сокращений и переменных. легко ошибиться с методом записи, а потом не понять, что имелось ввиду.

  #3     Элегантное программирование: искусство именования объектов
Сообщение 28 Dec 2013, 17:11
Ursego Аватара пользователя
СОЗДАТЕЛЬ ТЕМЫ
Canada, Ontario
Город: Toronto
Стаж: 11 лет 7 месяцев 5 дней
Постов: 10707
Лайкнули: 3448 раз
Карма: 33%
СССР: Днепропетровск
Пол: М
Лучше обращаться на: ты
Заход: 20 Nov 2023, 18:00

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

  #4     Элегантное программирование: искусство именования объектов
Сообщение 28 Dec 2013, 17:50
Cth Аватара пользователя
Canada, British Columbia
Город: Vancouver
Стаж: 10 лет 3 месяца 5 дней
Постов: 1550
Лайкнули: 312 раз
Карма: 21%
Пол: М
Заход: 09 Aug 2022, 19:36

я все не читал, но я бы еще упомянул об отступах для выделения операторных скобок (циклов, условий, функций, других вложенностей) (как в питоне, только там отступы - часть синтаксиса) и трижды упомянул бы о комментариях, иногда открываешь чужой код, а там ничего не откамменчено; это не фатально в случаях мелких скриптов, но если основной код занимает с сотню страниц без библиотек и функций... Да, иногда встречается код, который страшно читать. страшно, потому что кажется, что если его обфусцировать - он станет читабельнее.

  #5     Элегантное программирование: искусство именования объектов
Сообщение 28 Dec 2013, 18:06
Ursego Аватара пользователя
СОЗДАТЕЛЬ ТЕМЫ
Canada, Ontario
Город: Toronto
Стаж: 11 лет 7 месяцев 5 дней
Постов: 10707
Лайкнули: 3448 раз
Карма: 33%
СССР: Днепропетровск
Пол: М
Лучше обращаться на: ты
Заход: 20 Nov 2023, 18:00


  #6     Элегантное программирование: искусство именования объектов
Сообщение 29 Dec 2013, 20:42
Canada, Ontario
Город: Toronto
Стаж: 11 лет 6 месяцев 29 дней
Постов: 745
Лайкнули: 58 раз
Карма: 8%
Пол: М
Заход: 16 Jan 2021, 17:50
Переменные, соответствующие полям таблиц базы данных, называйте так-же, как эти поля
Идея кашерная
Только обычно надо перефигачить в верблюжью нотацию если пишешь на жабе или решётке

Вам есть что сказать по этой теме? Зарегистрируйтесь, и сможете оставлять комментарии
cron