Следует ли по-другому комментировать на функциональных языках? [закрыто]

Я только начинаю с функционального программирования, и мне интересно, как правильно комментировать мой код.

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

Как правильно комментировать функциональную программу? Должен ли я использовать тот же подход, что и в итеративном программировании?

Имя функции должно указывать, что вы делаете.

Реализация расскажет вам, как вы это делаете.

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

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

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

// map 'toUpperCase' over 'container' yielding 'result'
Container result = new Container();
for (int i=0; i < container.size(); i++) { 
             result.addToTail(container.atElement(i).toUpperCase());
}

Но это явно глупость на функциональном языке:

-- map 'toUpperCase' over 'list'
let result = map toUpperCase list

Лучше:

-- we need the FooBars in all uppercase for the Frobnitz-Interface
let result = map toUpperCase list

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

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

// returns a list of Employees    <-- not necessary
def GetEmployeeList: ...

// returns a list of Employees sorted by last name    <-- necessary
def GetEmployeeList: ...

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

Сам комментарий не должен содержать альтернативного описания тому, что делает код (который фактически выражается самим кодом), а скорее объяснение причин, почему код написан таким, какой он есть.

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

Я использую тот же подход к документированию всего моего кода:

• Используйте описательные имена,
• Добавляйте комментарии перед любой разумно сложной логикой, если нельзя избежать сложной логики,
• Написать обзор всей системы,

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

В 25 лет вы, как правило, лучше запоминаете вещи. По мере того, как вы становитесь старше и работаете с несколькими системами с унаследованным кодом (да, код, который вы пишете сегодня, станет унаследованным кодом через 10-15 лет), это может быть очень полезно при наличии комментариев.