Давайте всему, к чему будет обращение в коде (таблицам базы данных и их полям, классам, объектам, функциям, переменным и т.д.) осмысленные, описательные, объясняющие сами себя имена, которые сделают код легко понимаемым, сводя к минимуму (или вообще делающих ненужными) комментарии.
Используйте слова "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!
Как видите, имя переменной может рассказать целую историю! Это делает строки кода длинней, но её можно разбить на несколько - это лучше, чем тупо глазеть на переменную не имея никаких предположений что в ней хранится! И всё-же помните: вы - не Лев Толстой , так что этот совет - не правило, а исключение из него.
Сокращения (аббревиатуры)
Сокращайте слова только если смысл аббревиатуры будет более, чем очевиден.
Пытаясь уменьшить размер кода, мы зачастую сокращаем слова, используемые в именах таблиц, полей, переменных и т.д. Сокращаем иногда слегка, иногда значительно - это обычно зависит от практики, принятой в компании. В одном из проектов мне пришлось изрядно помучиться от очень жёстких правил сокращения - надо было обрубать всё, что попадается на глаза! Нельзя было использовать гласные (кроме начальных, например 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! )
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), и не пришлось бы ломать голову!