Я только начинаю с функционального программирования, и мне интересно, как правильно комментировать мой код.
Кажется, немного излишне комментировать короткую функцию, так как имена и подписи уже должны рассказать вам все, что вам нужно знать. Комментирование больших функций также кажется немного избыточным, поскольку они обычно состоят из меньших самоописательных функций.
Как правильно комментировать функциональную программу? Должен ли я использовать тот же подход, что и в итеративном программировании?
functional-programming
comments
Том Сквайрс
источник
источник
Ответы:
Имя функции должно указывать, что вы делаете.
Реализация расскажет вам, как вы это делаете.
Используйте комментарии, чтобы объяснить, почему вы это делаете.
источник
В этом вопросе определенно есть смысл, поскольку функциональные программы обычно находятся на другом уровне абстракции, чем императивные.
Из-за этого необходим другой стиль документации. В итеративных программах комментарий может быть полезен, как в следующем коде, потому что суть кода скрыта за образцом:
Но это явно глупость на функциональном языке:
Лучше:
источник
Причина, по которой мы документируем функцию, заключается в том, что читатели не хотят или не могут прочитать тело функции. По этой причине следует документировать большие функции даже на функциональных языках. Неважно, легко ли понять, что делает функция, посмотрев на ее реализацию.
источник
Функции должны быть прокомментированы, если одного имени функции и параметров недостаточно для указания контракта .
Вкратце, контракт определяет, что ожидает функция и что она гарантирует. Строго говоря, если
GetEmployeeList
возвращает отсортированный список, но не говорит об этом ни в имени функции, ни в комментарии, потребитель этой функции не должен полагаться на это поведение. Это недокументированная деталь реализации, и авторGetEmployeeList
может в любое время изменить это поведение.источник
Сам комментарий не должен содержать альтернативного описания тому, что делает код (который фактически выражается самим кодом), а скорее объяснение причин, почему код написан таким, какой он есть.
Тем не менее, я не вижу никаких причин, почему комментарий должен сам по себе отличаться на функциональном языке.
источник
Я использую тот же подход к документированию всего моего кода:
Если имя и тип подписи не говорят вам точно, что делает функция, вы обычно делаете это неправильно.
источник
В 25 лет вы, как правило, лучше запоминаете вещи. По мере того, как вы становитесь старше и работаете с несколькими системами с унаследованным кодом (да, код, который вы пишете сегодня, станет унаследованным кодом через 10-15 лет), это может быть очень полезно при наличии комментариев.
источник