Коментарии в коде

Сообщество не ориентир. Выбирай блок для массивных пояснений. Для остального дабл слэш. От языка тоже зависит.

но если дабл слэш много, а коментарии разные например почему так или что это или вопрос?
или выделить что-то внутри массивного блока

/* */ это C. // это C++. Остальное это либо ненужная отсебятина, либо особые комментарии для генератора документации типа doxygen.

Главное, что бы у тебя в коде было однообразно. :)

Используй формат doxygen, он многим привычен

От языка зависит, да.

Например в Rust комментарии имеют семантику

// Просто комментарий

/// Документация

А остальные варианты почти не используются.

Как ни странно, буду первым: настоящие джедаи каменты не пишут!

Вот пишешь-пишешь каменты – подробные, понятные. А потом оказывается, что их вообще никто не читает. Даже не пытается. Вместо этого тебя многократно долбят одни и те же люди одними и теми же вопросами, на которые ты уже ответил в каментах. Нах@# надо. Это банальное неуважение к моему времени.

А потом, когда это в конец достаёт и собираешься сваливать, с тебя требуют передать дела кому-то новенькому. Шо, опять? Дык оно ещё кроме всего прочего ни одной строчки в проекте написать не успело, что я ему буду передавать? А как напишет – пущай читает мои каменты.

Кто виноват, что ты в какой-то помойке работаешь?

Твоя проблема решается одной аббревиатурой: RTFM. Сказал и пошёл дальше свои дела делать (:

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

Ну и да, хоть тут и орут, что коменты не нужны, на мой взгляд это неверно. Лепить по комменту на каждую переменную не нужно, конечно, но обозначить назначение основных классов и методов надо обязательно, это поможет потом в первую очередь тебе же, когда будешь разбираться в своём коде и думать «шо за дебил это писал?».

Прежде всего надо комментировать неочевидные решения и взаимосвязи с другими частями кода. Чтобы потом ненароком ничего не сломать под девизом «можно лучше».

А вообще, ТС, держи: https://stackoverflow.com/questions/184618

Ну это входит в мое описание.

Тому що комментарii оформляются в зависимости от целей проекта.

Если ты планируешь зажать свой код, и сделать его малопонятным, то такие комментарии и пишешь.

+много

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

попробуй такие, по заветам мастеров

c = a + b; // Add a to b and store the result in c

// это C99. /**/ это и C++

они language-specific. во многих скриптовых языках еще для совместимости с gangba..shebang исрользуется #. проще всего настроить автоформатирование кода и не думать об этом.

А так же есть два диметрально противоположных мнения: одни считают, что комментарии не нужны, а другие, что комментировать нужно все подряд. Но как бы то ни было, дебилов всегда большинство.

Какие нравится такие и использую. Всё зависит от коментируемого кода.

Это колхозный комментарий, т.к. он не отражает интента и особенностей действия. Комментарии на каждой строке надо писать вот так:

c = a + b; // here we chose to use an addition operator in order to create a sum of specified values; remember that the order of evaluation itself is not specified, when refactoring one (or both) of the operands into expressions with side-effects; overflow checking is omitted in this particular case due to assertions at the start of this function; on invariants changes, grep sync_overflow_checking_foo_prologue

Тогда все будет понятно и регистранты выше, придя на твой код, будут довольны.

Java code style гугли и делай как там.

Правда посредине. С одной стороны если какой-то комментарий можно заменить грамотным именованием, то нужно так и сделать. Т.е. вместо

/**
 * Returns first name
 */
String getName() 

надо писать

String getFirstName()

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

Надо писать

/**
 * Returns first name if user data has been initialized or null
 */
String getFirstName()

не надо писать

String getFirstNameIfDataHasBeenInitializedOrNull();

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

void unsafeImmediateServiceShutdownCausingLossOfData()

вместо

/**
 * Imediately shuts down the service, causes loss of data
 */
void immediateShutdown()

т.к. использоваться будет редко, а в глаза бросаться должно.

А самые грамотные программисты ещё и расписывают всякую полезную ерунду, которую кодом выразить принципиально невозможно. Я до такого ещё не дорос. Но в целом перед началом кода функции, например, описывают, почему эта функция так написана. Условный пример:

/*
 * The following code uses bubble-sort algorithm because of better cache-locality.
 * It evicts less bytes of L1 cache than other algorithms and input size is insignificant
 * to cause issues because of quadratic complexity.
 */
...

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

Пиши коменты на понятном читателям языке. А то развелось вас, агентов иностранных!

есть ли более менее принятые сообществом типы комментариев?

Да, однострочные и многострочные. Все остальные, например в строке регулярного выражения, встречаются реже из-за их плохой читаемости.

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

современные ide умеют комментировать и раскомментировать блоки кода, просто нажми ctrl+/. вообще как угодно, и // и /**/ понимают и си, и с++. /// или //< - это комментарии doxygen: https://www.doxygen.nl/index.html

Пиши коменты на понятном читателям языке. А то развелось вас, агентов иностранных!

den73 залогинься!

может те кто читает просто не беспокоят

Лепить по комменту на каждую переменную не нужно, конечно, но обозначить назначение основных классов и методов надо обязательно

Дваждую. Что код делает, можно понять, почитав его, а вот чего афтар хотел этим кодом добиться — нет. Каково место этого куска в общей картине.

Общую картину, кстати, тоже не помешало бы где-то описать %)

Общую картину, кстати, тоже не помешало бы где-то описать %)

Ага, где-то в начале главного класса, думаю.

может те кто читает просто не беспокоят

А если непонятно, то молча страдают. :)

/*гнпмнгилоь оринри лгрл.
лриготлдь
олшдьдл
*/

/*** рпмроиродиол ***/

отличный комментарий. сразу понятно, что в коде происходит. так и пеши.

Увы, ни разу в жизни мне не доводилось слышать ничего похожего на «каменты непонятные»

Почему нет?

 > '1234567890' -split '(?<=.)(?#by2)(?=(?:..)+$)'
12
34
56
78
90

считаю, что для людей как то пофиг какой конкретно тип комментирования кода использовал разработчик — надо делать особое комментирование, когда надо, что бы оно могло читаться какими-то прогами — например автоматическим создателем мануалов — синтаксис, который они парсят и делай...

Там строчные комменты забанены. Нафиг так жить.