Стилі документації для коментування / кодування

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

У мене є вчитель, який каже, що ми повинні чітко перелічити кожен параметр з описом, навіть якщо є лише один. Це призводить до великої кількості повторень:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

Коли ви пишете кодову документацію, наскільки ви детально?

Для початку я погоджуюся, що рядок "Функція:" у вашому прикладі є абсолютно зайвим. Також мій досвід, коли люди навчали в школі додавати такий тип коментарів, продовжуючи додавати такий тип коментаря у свій виробничий код.

Хороші коментарі не повторюють те, що в коді. Вони відповідають на питання "Чому?" замість "Що?" або "Як?" Вони охоплюють очікування щодо вхідних даних, а також того, як код буде вести себе за певних умов. Вони охоплюють , чому алгоритм X був обраний замість алгоритму Y. Коротше кажучи, саме те , що не було б очевидно для кого - то ще ¹ від читання коду.

^{1: Хтось, хто знайомий з мовою, на якій написано код. Не пишіть коментарів, щоб навчати, коментуйте, щоб доповнити інформацію.}

У кількох мовах є функції генерації документів API, такі як Ruby, Java, C # і C ++ (за допомогою інструменту командного рядка). Якщо ви думаєте про це таким чином, це робить написання документів API набагато важливішим. Зрештою, він відповідає на питання "як мені це зробити ...?" Тому я не буду робити нічого подібного, як, Function: MyFunctionколи ім'я функції зрозуміле для всіх. Інструменти для генерації документів API досить розумні, щоб зробити це для мене. Однак корисні наступні деталі, особливо щодо публічних методів / функцій:

• Підсумок (що це робить і коли доречно резюме того, як ним користуватися)
• Список параметрів і що очікується
• Яке буде повернене значення (вихід)
• Будь-які винятки, які можна кинути явно і чому

Вони можуть стати корисними довідковими інструментами при спробі налагодження коду. Багато IDE також використовуватимуть документи API у своїх підказках щодо інструментів під час наведення курсору на ім’я функції.

Якщо мова йде без цих особливостей, коментарі допомагають, але майже не так сильно.

Якщо це метод публічного API, то так, ви повинні надати детальну документацію, особливо щодо параметрів та очікуваної поведінки. Багато людей вважають, що це може бути полегшено для приватних методів / функцій, YMMV.

В цілому я вважаю за краще писати чистий код (невеликі методи / функції, які добре спрацьовують одне і одне) з розумними назвами змінних. Це робить більшу частину коду самодокументуванням. Однак я, безумовно, завжди документую будь-які кращі випадки, використання паралельних і складних алгоритмів.

Коротше кажучи, подумайте про своє самопочуття як про щось гірше, ніж його носять о 3 годині ранку, 3 місяці. Ви будете вдячні за свої дивовижні публічні документи на відміну від з'ясування того, що означає параметр (булева прапор) ...

Це схоже на те, як більшість фреймворків -Doc розбирають документацію в коді (JavaDoc, PHPDoc тощо).

З Java, автоматично створений IDE:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

Це той самий формат, який використовується для створення Документації для вбудованих функцій мови - Приклад: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

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

Єдиний біт, який я часто знаходжу дещо зайвим - це опис повернення - зазвичай це майже ідентично моєму опису методу.

Для коментарів дві цілі:

1. Вони служать, щоб швидко нагадати вам, що робить ваш код, коли ви повернетесь до нього місяцями / роками пізніше. Таким чином, вам не доведеться перечитувати та аналізувати код, щоб оновити пам’ять.
2. Вони передають іншим людям, які можуть читати чи працювати з вашим кодом, що робить ваш код.

Звичайно, існує безліч різних способів підходу до цього, але чим ретельніше і послідовніше ви, тим краще. Ефективне коментування вимагає часу, щоб навчитися так само, як і ефективне програмування. Майте на увазі, що важко зрозуміти сенс коментарів у школі, оскільки ніщо над тим, над чим ви працюєте, все-таки є достатньо великим, щоб дійсно цього вимагати, але вони просто намагаються ознайомити його з вами. І зазвичай те, як навчити вас це робити - це стиль вашого професора, а не будь-який стандарт будь-яким способом. Розвивайте те, що працює для вас. І пам’ятайте ... є таке поняття, як дурний коментар! :) Приклад:

a += 1; //adds 1 to the value in a

Дійсно? Дякую! Лол

Мені подобається документація з веб-сайту PHP, тому я використовую щось подібне для своїх вбудованих коментарів та використання синтаксису PHPDoc. Дивіться приклад нижче.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

І як сказав @Larry Coleman, вбудовані коментарі повинні говорити, чому ви зробили якийсь фрагмент коду.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Якщо це стосується покоління Doc, то багатослівні коментарі (хоча і дратують) - це, мабуть, хороша річ. Хоча вам потрібно зробити це командною метою, щоб залишатися в курсі коментарів і тримати їх у курсі.

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

Я б швидше мав чіткий короткий коментований коментований код. Дайте мені кілька тестів із описовими твердженнями або методами, і я задоволений і поінформований.