Про абстрактные слова в идентификаторах · Заметки

Реальная история. Программист создал иерархию классов, которые делают некоторую обработку входных данных, функцию для применения обработчиков к данным назвал Apply().
Чуть позже понадобилось добавить в те же классы и другой режим обработки, "глобальный". Новую функцию он назвал Process().
Потом появилась ветка "специальных" обработчиков, которые обрели ещё одну функцию - DoFilter().
Функцию, которая пошагово переключает настройки обработчиков, он назвал Invoke().

В контексте программы с тем же успехом можно было бы назвать функции так:
Забубенить(), Зафигачить(), Забабахать() и Забацать().

·· [Continuing] ··

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

После переименования имена функций выглядят примерно так:

ApplyToLocalEvents()
ApplyToGlobalEvents()
DoSpecialFilter()
Invoke() - пока осталась с прежним именем, т.к. оно более не конфликтует по смыслу с прочими.

Внимательный читатель должен тут сказать: стоп, а как же слово "Special"? Оно ведь тоже абстрактное! Ну, на самом слово "Special" в названии пока что просто не удалось до конца понять и перевести в конкретное понятие - ведь этот район кода, написанный для настоящих героев анализа, изучался всего несколько дней. Как только будет найдено правильное слово - оно там будет вписано.

Из этой истории следует такой совет:
Избегайте абстрактных слов и их сокращений в именах классов и переменных, вроде:
interface, implementation, work, job, process, factory, singleton, data, special....
Используйте конкретные слова, имеющие отношения к решаемой задаче.

Например: povar.cook() выглядит куда понятнее, чем povar.job(). Даже если povar участвует в иерархии классов работников, все из которых имеют виртуальную функцию job(), может иметь смысл сделать ему cook(), а job() определить примерно как virtual TJobResult job(){ return cook(); }.

Вот ещё из реальной жизни:
CMidiPort => CPortmidiMidiPort (всё понятно - от универсального класса MIDI-порта унаследовали Portmidi реализацию)
Выглядит куда понятнее, чем:
CMidiInterface (интерфейс MIDI чего? порта, сообщения, устройства?) => CPortmidiImplementation (реализация, простите, Портмиди чего?)

Если названия классов отображают их предназначение, то слова вроде "Interface", "Implementation" выглядят уже излишними. С другой стороны, ни в коем случае нельзя упускать те слова, которые точно объясняют предназначение.

Помните, что изобилие абстракций не только делает код абсолютно нечитабельным, но и способно полностью выбить из головы программиста оконечную цель его работы!