Комментарии 41
Если что-то очевидно не для всех — это уже не капитанство. По мне так хорошая статья: многие продолжают засорять код комментами и тратить время на запутанные и быстроустаревающие доки на каждый чих. Если вашему коду нужны комменты — у вас проблемы с именованием сущностей и соглашениями по стилю (за исключением редких случаев).
Просто на эту тему уже столько всего говорено, а по факту все решается практикой. Больше практики, больше понимания того, как лучше, а как хуже. Даже мой комментарий вышел немного капитанским)
Невозможно начать практиковаться над правильностью написания кода, не зная общепринятых правил. Точнее не так. Конечно, можно практиковаться, но тогда могут выработаться свои, не похожие на общепринятые, правила разработки. Тогда, при работе в команде, могут возникнуть соответствующие недопонимания и проблемы.
Статья состоящая из капитанства на 102%.
Именно так. Эти правила давно известны в кругах программистов.
Я перевел и опубликовал эту статью по 2 причинам:
1. Здесь собраны общие правила, понятные даже ребенку сравнения, предостережения по тому, как не переусердствовать. Оригинал показался мне самодостаточным и самым полным из тех, что попадались моему глазу.
2. Данная статья нацелена на начинающих программистов, которые могут использовать ее как памятку в своих первых проектах.
Верхние слои в названиях содержат части бизнес-логики, нижние — части работы с обезличенными действиями.
Ну отлично. А что за Basket? Почему из него надо удалять предметы? Это актуально, или согласно новыми требования уже такого делать нельзя, а этот код просто остался для совместимости, а на самом деле он не удаляет, а помечает удаленным?
Если бы товар помечался, как удаленный, то и метод бы назывался markAsDeleted или как-то так.
А если вот сначала оно удалялось, а потом в середине проекта получилось так, что нужно было поменять логику на помечать как удаленный?
Менять название метода везде? А потом выяснится, что у вас так же были еще интеграции, которые расчитывали на этот метод, и поэтому вам нужно, что бы название точно осталось.
Написать второй метод и заменить первый на второй в тех местах где это нужно. Обычно выходит так что в одном месте надо чтобы удалялось а в другом чтобы помечалось. И можно пойти по пути вставки флажочков в код метода, что не есть гуд.
А доки как-то отвечают на все эти ваши "если"? Если вам во всех этих случаях требуется искать ответ в доках, разбираться почему старые названия методов не соответсвуют текущим реалиям — у вас полный бардак в проекте и все плохо спроектировано.
Менять название метода везде?
На это есть средства рефакторинга.
А потом выяснится, что у вас так же были еще интеграции, которые расчитывали на этот метод, и поэтому вам нужно, что бы название точно осталось.
Возможно, необходимо изначально как-то предусмотреть это?
Поидее если идёт работа над каким-то проектом то бизнес-сущности все знают. Иначе в каждом методе в котором есть слово баскет нужно писать а что это за баскет такой.
>Почему из него надо удалять предметы?
Потому что нужно такое действие, удаление.
>совместимость
Если произошла рассинхронизация после рефакторингов и изменения логики, то точно так же могли забыть поменять и комментарий к коду. А вообще, ради совместимости вносить изменения в метод, чтобы он делал не то что он обязан делать это странно. Проще и правильнее создать новый метод, который назвать markDeleted или что-то в этом роде.
Мой поинт в том что если скурпулёзно подходить к рефакторингу при изменениях, то всё будет понятно и без документации.
Мой поинт в том что если скурпулёзно подходить к рефакторингу при изменениях, то всё будет понятно и без документации.
Поидее если идёт работа над каким-то проектом то бизнес-сущности все знают. Иначе в каждом методе в котором есть слово баскет нужно писать а что это за баскет такой.
А где будут описаны бизнес-сущности? В коде? И так же бизнес-условия?
Да.
То есть вы вместо того, что бы собрать их в одной доке, предлагаете всем заинтересованным (среди которых не только программисты) искать их по разным файлам в коде?
Проектная документация — это отдельная вещь, исходя из бизнес-правил которой и кодируется бизнес-логика. Вот если бизнес-логика закодирована хорошо, то такому коду практически не требуются комментарии, потому что сам код будет более-мене ясно отражать суть того, что он делает и какую бизнес-задачу решает.
Плохому коду даже проектная документация, собранная в одном месте не поможет. Потому что вы в доках вы будете читать одно, а смотря на код вы будете видеть невесть что и думать, что же тут происходит-то?
И если что-то надо поменять, то это правится в ней как апдейт требований, после чего можно править код. И реализация изменения бизнес-требования может быть ну оччччень обширной. Или нет. Но в коде писать подобные вещи в виде комментов это зло.
Это Cart вероятнее всего, а не Basket:)
Если код состоит из тупых геттеров/сеттеров, а также методов типа save/update, тогда да. А если изначально подходить к именованию иначе, то можно добиться хорошей выразительности кода.
Предложите своё решение, заменяющее тупые геттеры/сеттеры, пожалуйста.
Ну, например, использование конструктора для передачи зависимостей. Адекватное название всяких «статусных» методов.
Например, вместо publication.setStatus(1) или publication.setStatus(publication.published) сделать publication.publish(), publication.unpublish() и так далее.
Тут есть две проблемы:
- Проблема в том, что когда я хочу работать с библиотекой X, я не хочу лезть в ее код, я хочу с ней работать.
- Код реально сложных вещей сложно понять, потому что вы не знаете бизнес-логику, которая за ним стоит.
Если вы в контексте проекта, то для вас почти любой будет читаем. А так будете страдать.
Индусский кэп
.
Что с хорошо написанным кодом работать проще и удобнее — очевидно. Но утверждение, что любой хороший код не требует обьяснений — это попытка на основе частного утверждения (I) посторить общее (A). В общем случае это не верно.
Бывает такой код, что и хороший, и ничего не понятно без обьяснений (или документации). Чтоб далеко не ходить — приведу в качестве примера процедуру поиска минимальной редактирующей последовательности или арифметический кодировщик.
Хороший код — наша лучшая документация