Хороший код — наша лучшая документация

Комментарии (29)

  • 11 августа 2017 в 11:19

    +3

    Статья состоящая из капитанства на 102%.
    • 11 августа 2017 в 11:34 (комментарий был изменён)

      0

      Если что-то очевидно не для всех — это уже не капитанство. По мне так хорошая статья: многие продолжают засорять код комментами и тратить время на запутанные и быстроустаревающие доки на каждый чих. Если вашему коду нужны комменты — у вас проблемы с именованием сущностей и соглашениями по стилю (за исключением редких случаев).

      • 11 августа 2017 в 12:03

        0

        Просто на эту тему уже столько всего говорено, а по факту все решается практикой. Больше практики, больше понимания того, как лучше, а как хуже. Даже мой комментарий вышел немного капитанским)

        • 11 августа 2017 в 13:39

          0

          Да, вы правы. Но любая практика начинается с теории.
          Невозможно начать практиковаться над правильностью написания кода, не зная общепринятых правил. Точнее не так. Конечно, можно практиковаться, но тогда могут выработаться свои, не похожие на общепринятые, правила разработки. Тогда, при работе в команде, могут возникнуть соответствующие недопонимания и проблемы.
    • 11 августа 2017 в 13:42 (комментарий был изменён)

      0

      Статья состоящая из капитанства на 102%.

      Именно так. Эти правила давно известны в кругах программистов.
      Я перевел и опубликовал эту статью по 2 причинам:

      1. Здесь собраны общие правила, понятные даже ребенку сравнения, предостережения по тому, как не переусердствовать. Оригинал показался мне самодостаточным и самым полным из тех, что попадались моему глазу.

      2. Данная статья нацелена на начинающих программистов, которые могут использовать ее как памятку в своих первых проектах.

  • 11 августа 2017 в 11:56

    +2

    Самодокументируемость кода — миф. Всегда нужно знать не что код делает, а зачем он это делает. Но сам код никогда вам об этом не расскажет.
    • 11 августа 2017 в 11:59

      0

      Еще как расскажет — deleteItemFromBasket (id).
      Верхние слои в названиях содержат части бизнес-логики, нижние — части работы с обезличенными действиями.
      • 11 августа 2017 в 12:26

        +1

        Ну отлично. А что за Basket? Почему из него надо удалять предметы? Это актуально, или согласно новыми требования уже такого делать нельзя, а этот код просто остался для совместимости, а на самом деле он не удаляет, а помечает удаленным?

        • 11 августа 2017 в 12:29

          0

          Если бы товар помечался, как удаленный, то и метод бы назывался markAsDeleted или как-то так.

          • 11 августа 2017 в 12:31 (комментарий был изменён)

            0

            А если вот сначала оно удалялось, а потом в середине проекта получилось так, что нужно было поменять логику на помечать как удаленный?
            Менять название метода везде? А потом выяснится, что у вас так же были еще интеграции, которые расчитывали на этот метод, и поэтому вам нужно, что бы название точно осталось.

            • 11 августа 2017 в 12:37

              0

              >Менять название метода везде
              Написать второй метод и заменить первый на второй в тех местах где это нужно. Обычно выходит так что в одном месте надо чтобы удалялось, а в другом чтобы помечалось. И можно пойти по пути вставки флажочков в код метода, что не есть гуд.
            • 11 августа 2017 в 12:37

              +1

              А доки как-то отвечают на все эти ваши «если»? Если вам во всех этих случаях требуется искать ответ в доках, разбираться почему старые названия методов не соответсвуют текущим реалиям — у вас полный бардак в проекте и все плохо спроектировано.

              • 11 августа 2017 в 12:40

                +1

                Нижнеуровневые доки нет, а верхнеуровневые почти на все.

            • 11 августа 2017 в 12:39

              0

              Менять название метода везде?

              На это есть средства рефакторинга.


              А потом выяснится, что у вас так же были еще интеграции, которые расчитывали на этот метод, и поэтому вам нужно, что бы название точно осталось.

              Возможно, необходимо изначально как-то предусмотреть это?

              • 11 августа 2017 в 12:40

                0

                Невозможно предусмотреть все, особенно, если у вас не водопад.

        • 11 августа 2017 в 12:33

          0

          >А что за Basket
          Поидее если идёт работа над каким-то проектом то бизнес-сущности все знают. Иначе в каждом методе в котором есть слово баскет нужно писать, а что это за баскет такой.
          >Почему из него надо удалять предметы?
          Потому что нужно такое действие, удаление.
          >совместимость
          Если произошла рассинхронизация после рефакторингов и изменения логики, то точно так же могли забыть поменять и комментарий к коду. А вообще, ради совместимости вносить изменения в метод, чтобы он делал не то что он обязан делать это странно. Проще и правильнее создать новый метод, который назвать markDeleted или что-то в этом роде.
          Мой поинт в том что если скурпулёзно подходить к рефакторингу при изменениях, то всё будет понятно и без документации.
          • 11 августа 2017 в 12:40

            0

            Мой поинт в том что если скурпулёзно подходить к рефакторингу при изменениях, то всё будет понятно и без документации.

            Поидее если идёт работа над каким-то проектом то бизнес-сущности все знают. Иначе в каждом методе в котором есть слово баскет нужно писать, а что это за баскет такой.

            А где будут описаны бизнес-сущности? В коде? И так же бизнес-условия?

            • 11 августа 2017 в 12:44

              0

              Да.

              • 11 августа 2017 в 12:45

                0

                То есть вы вместо того, что бы собрать их в одной доке, предлагаете всем заинтересованным (среди которых не только программисты) искать их по разным файлам в коде?

                • 11 августа 2017 в 12:54

                  0

                  Проектная документация — это отдельная вещь, исходя из бизнес-правил которой и кодируется бизнес-логика. Вот если бизнес-логика закодирована хорошо, то такому коду практически не требуются комментарии, потому что сам код будет более-мене ясно отражать суть того, что он делает и какую бизнес-задачу решает.


                  Плохому коду даже проектная документация, собранная в одном месте не поможет. Потому что вы в доках вы будете читать одно, а смотря на код вы будете видеть невесть что и думать, что же тут происходит-то?

            • 11 августа 2017 в 12:45

              +1

              В нашем проекте есть на каждые большие сущности описания бизнестребований. Где описывается что такое корзина, какие действия возможны с ней, и тп. Вроде это называется Красной Спецификацией.
              И если что-то надо поменять, то это правится в ней как апдейт требований, после чего можно править код. И реализация изменения бизнес-требования может быть ну оччччень обширной. Или нет. Но в коде писать подобные вещи в виде комментов это зло.
      • 11 августа 2017 в 13:30

        0

        Расскажет в очевидных/стандартных/распространенных случаях, но они таковы ведь далеко не всегда.
    • 11 августа 2017 в 12:06

      +1

      Если код состоит из тупых геттеров/сеттеров, а также методов типа save/update, тогда да. А если изначально подходить к именованию иначе, то можно добиться хорошей выразительности кода.

      • 11 августа 2017 в 13:29

        0

        Предложите своё решение, заменяющее тупые геттеры/сеттеры, пожалуйста.

        • 11 августа 2017 в 13:44

          0

          Ну, например, использование конструктора для передачи зависимостей. Адекватное название всяких «статусных» методов.


          Например, вместо publication.setStatus(1) или publication.setStatus(publication.published) сделать publication.publish(), publication.unpublish() и так далее.

  • 11 августа 2017 в 12:25

    +4

    Тут есть две проблемы:


    1. Проблема в том, что когда я хочу работать с библиотекой X, я не хочу лезть в ее код, я хочу с ней работать.
    2. Код реально сложных вещей сложно понять, потому что вы не знаете бизнес-логику, которая за ним стоит.

    Если вы в контексте проекта, то для вас почти любой будет читаем. А так будете страдать.

  • 11 августа 2017 в 12:39

    +2

    Такие статьи хороши, но как всегда истина где то рядом. Если рассматривать сферического коня в вакууме, то все ок. На деле в больших промышленных приложениях, которые разрабатывают одни, обслуживают другие, а поддерживают третьи разработчики — баги обычно исплавляются методом забивания нужного кода гвоздями напрямую, без учета архитектуры, увы (
  • 11 августа 2017 в 13:24

    +1

    Да уж, как техписатель я подтверждаю — с хорошо написанным кодом и работать хорошо и разбираться легче.
  • 11 августа 2017 в 13:28

    0

    Индусский кэп

© Habrahabr.ru