Комментарии + Markdown: Улучшаем читаемость кода для разработчиков

Комментарии + Markdown = 🖤

Одна из самых важных задач в кодинге – делать его понятным для других разработчиков и будущего себя. И для этого существуют 3 основных трюка:

1. Пишите более простые конструкции. If / else, вместо тернарников, for loop вместо filter + map + reduce (именно, когда вам приходится использовать все 3 в комбинации), заранее вычислять предикаты, присваивать их в union type и делать switch, вместо множества вложенный if / else.

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

3. Добавляйте комментарии в код.

И вот про последний пункт, редко можно найти полезную информацию, поэтому я выработал для себя несколько крутых принципов:

1. Comment Driven Development – я очень часто сначала пишу комментарии в функции о том, что она должна сделать, а потом только пишу код. Это позволяет заранее увидить и порешать логические коллизии.

2. Используйте Markdown.

Пример без Markdown:

// First comment
const foo = await bar()

if (foo) {
// Second comment
await helloWorld()
}

// Third comment
const ping = await ping()

А теперь скажите: First comment и Third comment связаны или нет? То есть, это следующий этап кода или часть предыдущего?

Ответ тут можно только гадать.

А вот если использовать Markdown:

// # First comment
const foo = await bar()

if (foo) {
// ## Second comment
await helloWorld()
}

// # Third comment
const ping = await ping()

Как вы видите, я обозначаю через Markdown "главы" кода, как если бы это был обычный текст. Благодаря этому можно четко понимать, что Third comment – это новая глава (следующий этап).

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

А какие вы используете трюки для написания комментариев?