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

25

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

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

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

Том Сквайрс
источник
7
«поскольку они обычно состоят из меньших самоописательных функций». - это, в принципе, не отличается в императивных языках. Тем не менее, часто не сразу понятно, что будет делать большая функция в конце: всегда можно вывести ее из самого кода, но если это занимает значительно больше времени, чем чтение комментария, вы должны предоставить его.
оставлено около
2
Я не согласен. Поскольку у функциональных языков нет побочных эффектов, вы точно знаете, что он будет делать в конце, верните значение с заданной сигнатурой
Том Сквайр
8
не все функциональные языки чисты, у некоторых есть побочные эффекты.
Танос Папатанасиу
1
Но прокомментируйте, что вы чувствуете, чтобы комментировать ... Это слишком много
gd1
1
Есть ли риск, что в вашем проекте есть другие участники, которые не знакомы с функциональными языками? Им может понадобиться дополнительная помощь.
Джефф

Ответы:

84

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

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

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

Шон Макмиллан
источник
1
Отличный ответ, это убивает меня, когда я вижу код, заваленный комментариями, которые объясняют, что и как (что видно из самого кода), но оставляют меня угадывать, почему.
Эрик Уилсон
32
и это верно независимо от парадигмы
JK.
2
Это, вероятно, само собой разумеется, но вы также должны добавить комментарии о том, что и как в случае, если код сложный или запутанный и требует такого объяснения. Конечно, подобного кода в любом случае также следует избегать, но это не всегда возможно.
user606723
3
Хотя этот ответ очень прост, а простота имеет большую ценность, он не совсем верен. Имя функции часто не описывает и не может описать «что» достаточно подробно, поэтому часто необходима документация (например, для описания крайних случаев). Документация часто вставляется в комментарии.
luiscubal
2
Возможно, имя функции должно также объяснять, почему она это делает - когда это возможно.
Ям Маркович
14

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

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

// 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
Инго
источник
8
дедушка всегда говорит мне документировать почему, а не что. Поэтому я бы использовал последнюю версию для императивного кода.
Саймон Бергот
3
Твой дедушка прав. Я просто хотел продемонстрировать, что определенные комментарии, которые, тем не менее, имеют смысл в императивном царстве, абсолютно бесполезны в функциональности.
Инго
11

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

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

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

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

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

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

Heinzi
источник
2

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

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

perdian
источник
1

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

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

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

dan_waterworth
источник
0

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

Майкл Райли - AKA Gunny
источник