Мы все согласны. Документирование кода - пустая трата времени и немалые затраты. Гораздо лучше обратиться непосредственно к коду, если вы хотите понять, как программа работает изнутри.
Конечно, намерение хорошее, но что, если мы натолкнемся на такой фрагмент кода?

const f = (st, p) => p.filter((i) => 
                  i.title?i.title.includes(st):false||
                  i.keywords?i.keywords.includes(st):false);

Код JavaScript работает отлично. Он делает свою работу правильно. Но в чем именно его работа?

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

Как говорит Мартин Фаулер:

«Любой дурак может написать код, понятный компьютеру. Хорошие программисты пишут код, понятный людям ».

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

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

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

Один из способов максимально приблизиться к приемлемому результату - представить одного из своих коллег читателем вашего кода или, что еще лучше, напрямую спросить его, понятен ли код.

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

При этом мы можем переписать приведенный выше код, придав ему более человеческий вид, с еще одним шансом документировать себя:

function getFilteredPages(searchText, pages) {
  let isInTitle = (item) => item.title?
                            item.title.includes(searchText)
                            :false;
  let isInTagKeywords = (item) => item.keywords?
                            item.keywords.includes(searchText)
                            :false;
  return pages.filter(item => isInTitle(item) ||
                              isInTagKeywords(item));
}

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