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

Уровни, о которых я буду говорить, следующие:

  • Макроуровень: что означает этот жаргон и как работает бизнес?
  • Мезоуровень: как процессы протекают через наше приложение?
  • Микроуровень: как работает этот код и почему он здесь?

Что означает этот жаргон и как работает бизнес?

Когда вы новичок в команде, вы не будете понимать некоторые слова, которые люди вокруг вас используют ежедневно. Это нормально. В какой-то момент вам нужно будет узнать, что они означают, чтобы иметь возможность внести свой вклад в бизнес и, в частности, в приложение. Другими словами, вам нужно знать, какие домены есть в компании. Домены — это концепция из DDD (Domain-driven design). Это означает, что вы структурируете свой код в очень конкретных случаях использования вашего приложения. Используемый здесь язык специфичен для бизнеса, а не для языка программирования. Это означает, что если вы говорите о конкретном домене, давайте перейдем к «Проверке», вы можете поговорить с любым в компании, и они смогут понять, о чем вы говорите.

Хорошо… так что это значит? Ну, это означает, что вам нужно задокументировать все домены, которые существуют в вашем приложении и в вашем бизнесе. Новые сотрудники не будут точно знать, как работает ваш бизнес в деталях, поэтому документирование различных доменов и жаргона позволит им быстро освоиться при общении с кем-либо в компании. Указав точно, что означает каждый домен и жаргон, вы не оставляете места для путаницы в отношении того, что может иметь в виду другой человек.

Давайте рассмотрим пример:

While [domain] I encountered a bug in the system.

Вы можете заменить домен на что-то конкретное для бизнеса, в этом случае давайте использовать «Проверка». Это означает: При проверке я обнаружил ошибку в системе.

Когда у вас нет четкой структуры приложения и нет документации о том, как обрабатывать ваше приложение, вы потратите много времени на поиск в коде, чтобы найти, где возникла ошибка. Когда у вас есть очень четкая структура приложения, но нет документации, вы, по крайней мере, будете знать, в каком разделе искать какие-либо ошибки. Вы не будете точно знать, где именно, но рамки поиска значительно сократятся. Когда у вас нет четкой структуры приложения, но у вас отличная документация, вы сможете точно определить правильное место для исправления ошибки, и если у вас есть и четкая структура приложения, и отличная документация, у вас будет ошибка. исправлено в кратчайшие сроки.

Таким образом, документирование предметной области и жаргона поможет вам быстро освоить новых сотрудников, а также поможет быстрее устранять ошибки.

Как процессы протекают через наше приложение?

Когда вы новичок в кодовой базе, может быть очень сложно понять, как протекают процессы. Вы можете довольно легко найти точки входа и ответы, но выяснить, как работают процессы, просто взглянув на код, очень сложно. Найти основные процессы в системе обычно легче, если приложение хорошо структурировано. Если основные цели системы не сразу ясны, взглянув на структуру папок, это то, что вы должны задокументировать.

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

Итак, основная цель документации — объяснить, как работает приложение, но вы также должны документировать свой код, верно? Правильно, но это только один из уровней, которые вы должны задокументировать. Итак, давайте перейдем к этому прямо сейчас.

Как работает этот код и почему он здесь?

Наконец-то мы подошли к самой простой, но часто упускаемой из виду части этого путешествия по документации. Документирование кода — это то, чем занимается большинство команд, но не все команды делают это так эффективно, как могли бы. Я много раз сталкивался с собственными ошибками в документации. Здесь я использую самодокументируемые имена методов в своем коде, но затем добавляю комментарий, который по существу копирует имя метода.

Например:

generateTransactionObjectForPurchase

с удивительным комментарием:

This method generates a transaction object for a purchase

Тогда я просто думаю про себя: «Отлично, что буквально ничего не сказал мне о том, зачем это нужно». Гораздо лучшим комментарием было бы что-то вроде:

We need to generate specific transactions from this purchase to be able to submit this to a payment provider.

Оно по-прежнему соответствует названию метода, но объясняет, почему эта часть процесса необходима и какое место она занимает в потоке. Когда приходит время рефакторинга, разработчик знает, почему этот код здесь и для какой цели он служит. Может случиться так, что код больше не нужен, и в этом случае его можно просто удалить. Но если документация этого не объясняет, вы не узнаете, нужно ли это, не изучая код. Этот разработчик может стать вами через год, так что сделайте себе огромное одолжение и объясните, зачем нужен код. Это нормально, если объяснение занимает несколько строк, потому что это только поможет вам быстрее отладить текущую ситуацию.

Вывод

В этом посте я объяснил, почему документация очень важна для проекта на трех разных уровнях:

  • Макроуровень: что означает жаргон компании и как работает бизнес?
  • Мезоуровень: как процессы протекают через наше приложение?
  • Микроуровень: как работает этот код, зачем он здесь и какое место он занимает в потоке процесса?

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

Иметь структуру приложения, которую можно легко понять, просто взглянув на имена папок, очень сложно и требует времени. Если вы не можете позаботиться об этом (сразу), наличие отличной документации все равно поможет новым сотрудникам быстрее внести свой вклад в приложение.

Если у вас есть что добавить к этому сообщению, я буду рад услышать от вас в Твиттере!

Опубликовано: 26 февраля 2020 г.

Первоначально опубликовано на https://roelofjanelsinga.com.