Комментарии + 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 – это новая глава (следующий этап).
Вот таким легким движением руки, ваши комментарии приобретают гораздо больше контекста и понятности для других разрабов
А какие вы используете трюки для написания комментариев?