Чи варто коментувати по-різному у функціональних мовах? [зачинено]

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

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

Який правильний спосіб коментувати функціональну програму? Чи слід використовувати той самий підхід, що і в ітеративному програмуванні?

Назва функції повинна говорити, що ви робите.

Реалізація розповість, як ви це робите.

Використовуйте коментарі, щоб пояснити, чому ви це робите.

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

Через це потрібен інший стиль документації. У ітеративних програмах коментар може бути корисним, як у наступному коді, оскільки суть коду прихована за котловою панеллю:

// 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 років), це може бути дуже корисно, якщо є коментарі.