Прокоментувати до або після відповідного коду [закрито]

Якщо припустити, що коментар не підходить (або не може перейти) у рядку, до якого він стосується, чи слід написати коментар перед кодом чи після?

Ну, де б не могли майбутні читачі зрозуміти сферу коментаря. Іншими словами, де б більшість програмістів / скрипторів не висловлювали таких коментарів.

Тож де більшість програмістів / скрипторів ставлять коментар: до чи після його коду?

Якщо ваша відповідь стосується лише певних мов, будь ласка, вкажіть, на якій.

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

Я б прокоментував вбудований текст або перед кодом, до якого слід застосувати коментар. Сенс коментарів полягає в тому, щоб отримати базове розуміння того, що робить код, без необхідності читати сам код. Тому має сенс розміщувати коментарі перед описаним кодом.

Microsoft каже, що було б хорошою практикою програмування починати процедури з невеликого коментаря. (Вони не згадують про коментарі після процедур) MSDN Посилання стосується VisualBasic, але воно стосується більшості мов програмування, на мою думку.

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

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

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

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

Тож де більшість програмістів / скрипторів ставлять коментар: до чи після його коду?

За багато років програмування, що використовує різні мови, я не пам'ятаю, щоб бачити будь-який код будь-якою мовою, де коментар розміщується в новому рядку після коду, на який він посилається. Принаймні, в США стандарт фактичного коментування коментується або перед кодом, або в тому ж рядку, що слідує за кодом. Написання ваших коментарів після відповідного коду запрошує тест на наркотики, психіатричну оцінку та / або побачення з парою плоскогубців та факелом.

Єдиний виняток, який я можу придумати, - це коментар, що позначає кінець раніше коментованого розділу, як це:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Джеф Раскін написав добре продуманий твір на коментарі, які варто прочитати. Він не каже, чи ставить свої коментарі перед кодом або після нього, але він каже, що він ніколи не ставить їх у порядок, і я ставлю на гроші багато грошей, які він не ставить після них.

Спробуйте коментувати лише там, де це дійсно необхідно; Код повинен намагатися самодокументувати, коли це можливо.

Однак, розміщення може залежати: Якщо ви використовуєте окремий рядок для коментаря, поставте його перед фактичним кодом. Якщо у вас є на одній лінії, поставте його після.

// this workaround is required to make the compiler happy
int i = 0;

Vs.

int i = 0; // make the compiler happy

Але ніколи:

int i = 0;
// this workaround is required to make the compiler happy

Я насправді не великий фанат коментарів. Під час курсу інженерії програмного забезпечення мене познайомили з ідеєю коду самодокументування. Код - єдина на 100% гарантована правильна документація сама по собі - коментарі потрібно оновлювати, ретельно будувати та відповідати, інакше вони є пастками, які можуть бути гіршими, ніж коментарі. Лише я не почав працювати в магазині C ++ зі строгим керівництвом по стилю та змістовними умовами іменування, що я справді втілив цю концепцію.

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

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

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

Гаразд, я зроблю випадок "після": код завжди повинен бути первинною документацією, тоді як коментар (який не має семантичного значення) - це як пояснення в дужках. Тому розміщення коментаря нижче коду, який потребує пояснення, залишає код як основне пояснення, а просто використовує коментар для роз'яснення. Наприклад,

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

Якщо ви поставите коментар перед тестом, читач, як правило, читає коментар як основну річ і може не читати код уважно, не розуміючи, що їх ввели в оману:

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

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

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

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

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

На щастя, коментар може надходити над або під фрагментом коду, і все ж не залишати сумнівів щодо того, до якого коду він відноситься, шляхом належного використання порожніх рядків. Звичайно, програмісти, які не звертають уваги на використання порожніх рядків, не знають, про що я говорю; якщо ви одна з таких, будь ласка, пропустіть цю відповідь і продовжуйте своє життя. Але програмісти, які звертають увагу на порожні рядки, дуже добре знають, що порожні рядки використовуються для поділу коду на логічні об'єкти. Отже, якщо ви бачите таке:

[blank line]
/* comment */
{ code }
[blank line]

Ви знаєте, що коментар належить до коду, і він говорить вам, що робить код. Беручи до уваги, якщо ви бачите таке:

[blank line]
{ code }
/* comment */
[blank line]

Знову ви дуже добре знаєте, що коментар належить до цього коду, і це з’ясування того, як код робить те, що робить.

Коментарі вище найкращі.

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

Код може (і повинен) бути "самодокументуванням", але якщо вам доведеться прочитати та зрозуміти кожен рядок коду, щоб зрозуміти, як працює метод. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

Коли я переслідував цю тему, я виявив, що більшість систем для документування, що читаються на комп'ютері (Doc XML, Doxygen, Java doc тощо) очікують, що коментар надійде перед кодом, на який він стосується, - краще залишатися сумісним із цим стандартом.

Я також згоден з потоком SO - Чи слід додавати коментарі після блоків коду, а не раніше? ..

Я також вважаю за краще знати спереду ...

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

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

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