Хороший код — наша лучшая документация
Комментарии (29)
AstarothAst
11 августа 2017 в 11:19
+3↑
↓
Статья состоящая из капитанства на 102%.
i360u
11 августа 2017 в 11:34 (комментарий был изменён)
0↑
↓
Если что-то очевидно не для всех — это уже не капитанство. По мне так хорошая статья: многие продолжают засорять код комментами и тратить время на запутанные и быстроустаревающие доки на каждый чих. Если вашему коду нужны комменты — у вас проблемы с именованием сущностей и соглашениями по стилю (за исключением редких случаев).
franzose
11 августа 2017 в 12:03
0↑
↓
Просто на эту тему уже столько всего говорено, а по факту все решается практикой. Больше практики, больше понимания того, как лучше, а как хуже. Даже мой комментарий вышел немного капитанским)
velkonost
11 августа 2017 в 13:39
0↑
↓
Да, вы правы. Но любая практика начинается с теории.
Невозможно начать практиковаться над правильностью написания кода, не зная общепринятых правил. Точнее не так. Конечно, можно практиковаться, но тогда могут выработаться свои, не похожие на общепринятые, правила разработки. Тогда, при работе в команде, могут возникнуть соответствующие недопонимания и проблемы.
-
velkonost
11 августа 2017 в 13:42 (комментарий был изменён)
0↑
↓
Статья состоящая из капитанства на 102%.
Именно так. Эти правила давно известны в кругах программистов.
Я перевел и опубликовал эту статью по 2 причинам:1. Здесь собраны общие правила, понятные даже ребенку сравнения, предостережения по тому, как не переусердствовать. Оригинал показался мне самодостаточным и самым полным из тех, что попадались моему глазу.
2. Данная статья нацелена на начинающих программистов, которые могут использовать ее как памятку в своих первых проектах.
AlexZaharow
11 августа 2017 в 11:56
+2↑
↓
Самодокументируемость кода — миф. Всегда нужно знать не что код делает, а зачем он это делает. Но сам код никогда вам об этом не расскажет.11 августа 2017 в 11:59
0↑
↓
Еще как расскажет — deleteItemFromBasket (id).
Верхние слои в названиях содержат части бизнес-логики, нижние — части работы с обезличенными действиями.
SirEdvin
11 августа 2017 в 12:26
+1↑
↓
Ну отлично. А что за Basket? Почему из него надо удалять предметы? Это актуально, или согласно новыми требования уже такого делать нельзя, а этот код просто остался для совместимости, а на самом деле он не удаляет, а помечает удаленным?
-
franzose
11 августа 2017 в 12:29
0↑
↓
Если бы товар помечался, как удаленный, то и метод бы назывался markAsDeleted или как-то так.
-
SirEdvin
11 августа 2017 в 12:31 (комментарий был изменён)
0↑
↓
А если вот сначала оно удалялось, а потом в середине проекта получилось так, что нужно было поменять логику на помечать как удаленный?
Менять название метода везде? А потом выяснится, что у вас так же были еще интеграции, которые расчитывали на этот метод, и поэтому вам нужно, что бы название точно осталось.11 августа 2017 в 12:37
0↑
↓
>Менять название метода везде
Написать второй метод и заменить первый на второй в тех местах где это нужно. Обычно выходит так что в одном месте надо чтобы удалялось, а в другом чтобы помечалось. И можно пойти по пути вставки флажочков в код метода, что не есть гуд.-
i360u
11 августа 2017 в 12:37
+1↑
↓
А доки как-то отвечают на все эти ваши «если»? Если вам во всех этих случаях требуется искать ответ в доках, разбираться почему старые названия методов не соответсвуют текущим реалиям — у вас полный бардак в проекте и все плохо спроектировано.
-
SirEdvin
11 августа 2017 в 12:40
+1↑
↓
Нижнеуровневые доки нет, а верхнеуровневые почти на все.
-
franzose
11 августа 2017 в 12:39
0↑
↓
Менять название метода везде?
На это есть средства рефакторинга.
А потом выяснится, что у вас так же были еще интеграции, которые расчитывали на этот метод, и поэтому вам нужно, что бы название точно осталось.
Возможно, необходимо изначально как-то предусмотреть это?
-
SirEdvin
11 августа 2017 в 12:40
0↑
↓
Невозможно предусмотреть все, особенно, если у вас не водопад.
11 августа 2017 в 12:33
0↑
↓
>А что за Basket
Поидее если идёт работа над каким-то проектом то бизнес-сущности все знают. Иначе в каждом методе в котором есть слово баскет нужно писать, а что это за баскет такой.
>Почему из него надо удалять предметы?
Потому что нужно такое действие, удаление.
>совместимость
Если произошла рассинхронизация после рефакторингов и изменения логики, то точно так же могли забыть поменять и комментарий к коду. А вообще, ради совместимости вносить изменения в метод, чтобы он делал не то что он обязан делать это странно. Проще и правильнее создать новый метод, который назвать markDeleted или что-то в этом роде.
Мой поинт в том что если скурпулёзно подходить к рефакторингу при изменениях, то всё будет понятно и без документации.-
SirEdvin
11 августа 2017 в 12:40
0↑
↓
Мой поинт в том что если скурпулёзно подходить к рефакторингу при изменениях, то всё будет понятно и без документации.
Поидее если идёт работа над каким-то проектом то бизнес-сущности все знают. Иначе в каждом методе в котором есть слово баскет нужно писать, а что это за баскет такой.
А где будут описаны бизнес-сущности? В коде? И так же бизнес-условия?
-
franzose
11 августа 2017 в 12:44
0↑
↓
Да.
-
SirEdvin
11 августа 2017 в 12:45
0↑
↓
То есть вы вместо того, что бы собрать их в одной доке, предлагаете всем заинтересованным (среди которых не только программисты) искать их по разным файлам в коде?
-
franzose
11 августа 2017 в 12:54
0↑
↓
Проектная документация — это отдельная вещь, исходя из бизнес-правил которой и кодируется бизнес-логика. Вот если бизнес-логика закодирована хорошо, то такому коду практически не требуются комментарии, потому что сам код будет более-мене ясно отражать суть того, что он делает и какую бизнес-задачу решает.
Плохому коду даже проектная документация, собранная в одном месте не поможет. Потому что вы в доках вы будете читать одно, а смотря на код вы будете видеть невесть что и думать, что же тут происходит-то?
11 августа 2017 в 12:45
+1↑
↓
В нашем проекте есть на каждые большие сущности описания бизнестребований. Где описывается что такое корзина, какие действия возможны с ней, и тп. Вроде это называется Красной Спецификацией.
И если что-то надо поменять, то это правится в ней как апдейт требований, после чего можно править код. И реализация изменения бизнес-требования может быть ну оччччень обширной. Или нет. Но в коде писать подобные вещи в виде комментов это зло.
dom1n1k
11 августа 2017 в 13:30
0↑
↓
Расскажет в очевидных/стандартных/распространенных случаях, но они таковы ведь далеко не всегда.
-
franzose
11 августа 2017 в 12:06
+1↑
↓
Если код состоит из тупых геттеров/сеттеров, а также методов типа save/update, тогда да. А если изначально подходить к именованию иначе, то можно добиться хорошей выразительности кода.
maxru
11 августа 2017 в 13:29
0↑
↓
Предложите своё решение, заменяющее тупые геттеры/сеттеры, пожалуйста.
-
franzose
11 августа 2017 в 13:44
0↑
↓
Ну, например, использование конструктора для передачи зависимостей. Адекватное название всяких «статусных» методов.
Например, вместо
publication.setStatus(1)илиpublication.setStatus(publication.published)сделатьpublication.publish(),publication.unpublish()и так далее.
-
SirEdvin
11 августа 2017 в 12:25
+4↑
↓
Тут есть две проблемы:
- Проблема в том, что когда я хочу работать с библиотекой X, я не хочу лезть в ее код, я хочу с ней работать.
- Код реально сложных вещей сложно понять, потому что вы не знаете бизнес-логику, которая за ним стоит.
Если вы в контексте проекта, то для вас почти любой будет читаем. А так будете страдать.
11 августа 2017 в 12:39
+2↑
↓
Такие статьи хороши, но как всегда истина где то рядом. Если рассматривать сферического коня в вакууме, то все ок. На деле в больших промышленных приложениях, которые разрабатывают одни, обслуживают другие, а поддерживают третьи разработчики — баги обычно исплавляются методом забивания нужного кода гвоздями напрямую, без учета архитектуры, увы (11 августа 2017 в 13:24
+1↑
↓
Да уж, как техписатель я подтверждаю — с хорошо написанным кодом и работать хорошо и разбираться легче.-
maxru
11 августа 2017 в 13:28
0↑
↓
Индусский кэп
