Галерея стилей комментариев... опубликуйте, как вы пишете свои комментарии

Question

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

Мне любопытно посмотреть, что люди считают лучшим способом стилизовать комментарии, разделы разделов и т. Д. Это может быть для html, php или чего-либо еще на самом деле.

Answer 1

PHP:
Лично я пользуюсь // для всего внутри метода / функции. Это раздражает, если кто-то использует /* */ потому что это затрудняет комментирование блоков кода

В целях документации я использую то, что использует phpdoc, что очень похоже на javadoc.

/**
 * Overall description
 * @keyword - description
 */

Обычно хорошим правилом является то, что если вы идете 15-20 строк без каких-либо комментариев, вам нужно добавить несколько комментариев, если код не говорит само за себя. Хотя в то время вы можете подумать, что запомните свою функцию на 500 строк, а все, что вы делаете, часто не будет. Если это кто-то другой пытается зайти и понять ваш код, ему будет только труднее!

Answer 2

В AS3 я использую это:

/**
 * 
 * to comment (if necessary) a method or a group of related methods
 *
 */

пока я использую это:

//

для однострочных комментариев.

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

Answer 3

Боковой узел (Быстрая ссылка, не мой): http://www.heartysoft.com/ninja-coding-code-comments

Почему я не люблю комментарии

Основная причина, по которой я стараюсь не комментировать свой код, - это концепция самообъяснимого кода. Код должен быть понятен самому себе - каждый, кто читает код, должен понимать, что происходит (конечно, с учетом определенных предметных знаний). Полагаться на комментарии, чтобы объяснить, что происходит, вряд ли хорошая идея. Код будет меняться гораздо чаще, чем обновляться комментарии. Независимо от того, насколько бдительна ваша команда, это обязательно произойдет. В лучшем случае это может привести к несколько устаревшим комментариям. В худшем случае устаревшие комментарии могут полностью вводить в заблуждение относительно того, что на самом деле делает код.

-

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

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

В крайних случаях (например, проблемы, связанные с ОС) я пытаюсь найти общедоступный веб-сайт, где обсуждается проблема, и добавить ссылку. Если в будущем разорвется ссылка - случится дерьмо.

-

AS3:

/**
 * This is a usual doc comment for a type or property.
 */

/*
 * This is a marker of a particular longer section of code.
 */

// This is a single line comment before a or at end of a line of code.