Я бы немного переформулировал основное послание: «Умейте видеть абстракции вовремя». Как старательно не проектируй, посреди реализации оказывается, что вот этот наследник использует только отрытый интерфейс родителя, а тот класс только какое-то время соответствовал этому интерфейсу, да и то только потому, что брал на себя не свои функции. К сожалению, многие абстракции кристаллизуются только после определенного времени разработки или даже использования системы. Угадать их заранее, по-моему, сроди ясновидению.
Но это не значит, что не надо стараться :)
Комментарии становятся почти (за исключением сложных мест) не нужны, если придуманы адекватные названия. Например, функция, которая добавляет к аргументу 5, если тот отрицательный, должна быть названа add5IfNegative, а не просто add5.
Но здесь появляется две проблемы
1. На удивление часто длинные названия считаются плохими, потому что замедляют работу и т.п. Прям религия какая-то…
2. Если разработчик не знает достаточно хорошо английский или не умеет лаконично выражать мысль, то лучше уж пусть комментирует на русском. Впрочем, в этой ситуации и комментарий может не спасти. Помню, метод, который возвращал объект, находящийся в недопустимом месте, в начальную позицию, назывался testForPlace. Вроде и название не из одной буквы, но понять назначение без изучения исходников было нереально. Конечно, метод был с комментарием — цитирую: «Проверка места»
Но это не значит, что не надо стараться :)
Но здесь появляется две проблемы
1. На удивление часто длинные названия считаются плохими, потому что замедляют работу и т.п. Прям религия какая-то…
2. Если разработчик не знает достаточно хорошо английский или не умеет лаконично выражать мысль, то лучше уж пусть комментирует на русском. Впрочем, в этой ситуации и комментарий может не спасти. Помню, метод, который возвращал объект, находящийся в недопустимом месте, в начальную позицию, назывался testForPlace. Вроде и название не из одной буквы, но понять назначение без изучения исходников было нереально. Конечно, метод был с комментарием — цитирую: «Проверка места»