Форматирование блока комментариев

Question

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

---

Первый (звездочка на каждой линии)

/* 
* line 1 
* line 2 
* line 3 
*/ 

Второй (минимальное количество звездочками)

/* 
line 1 
line 2 
line 3 
*/ 

Answer 1

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

Answer 2

Это (возможно) более читаемо или лучше выглядит. В течение некоторого времени люди использовали искусство ASCII, например.

/********************* 
* here is the doc * 
*********************/ 

или что-то в этом роде.

Answer 3

Легче увидеть, где начинается и заканчивается комментарий.

Нужно только просканировать левый столбец до тех пор, пока звездочки не «выбегут», чтобы найти следующий бит кода.

Где первый метод ломается, когда приходит время переписать комментарии. Теперь это требует переформатирования строк, чтобы вывести звездочки. Это не-нет, если у вас нет инструмента для этого автоматически.

В Макконнелле «Совершенный код» (второе издание), стр 790, он говорит:

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

Дело в том, что вы должны обратить внимание на то, как вы проводите время. Если вы тратите много времени на ввод и удаление [текста], чтобы сделать звездочки, вы не программируете; вы теряете время. Найдите более эффективный стиль.

Answer 4

Основная причина связана с документами PHP.

составителей документация, такие как PHPDoc построена для разбора блоков комментариев в этой форме, пример оформленного комментария блока следующим образом:

/** 
* Page-Level DocBlock 
* @package MyPackage 
* @category mycategory 
*/ 

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

Кроме того, взглянув на Zend Coding Standards - Inline Documentation, также указывается, что вы должны использовать этот тип комментариев для таких синтаксических анализаторов и читаемости.

Answer 5

Мне это нравится, потому что он визуально отличает код с кодом и документацию.

Если я хочу, чтобы закомментировать кучу кода, это:

/* 
int i; 
someCode(i); 
print i; 
*/ 

Гораздо лучше, потому что я могу либо переместить начало/конец части, чтобы включить его часть, или просто удалить две строки, чтобы включить все это. В другом формате я не могу этого сделать. В результате для документации лучше использовать другой стиль, потому что вы никогда не пытаетесь «раскомментировать» документацию.

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

На линии комментарии для закомментированного кода

Мне нравится этот лучше закомментирован код:

// int i; 
// someCode(i); 
// print i; 

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

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

Обратите внимание на разницу в синтаксисе SO Выделения, когда я закомментировать этот:

/** 
* Does something to i and then prints i 
*/ 
public void messWithI() { 
    int i; 
    someCode(i); 
    print i; 
} 

с блоком комментариев:

/*/** 
* Does something to i and then prints i 
*/ 
public void messWithI() { 
    int i; 
    someCode(i); 
    print i; 
}*/ 

С Строчка Комментарии:

// /** 
// * Does something to i and then prints i 
// */ 
// public void messWithI() { 
//  int i; 
//  someCode(i); 
//  print i; 
// } 

Причина вам нужен богатый редактор для этого, так как если вы должны применять/удалять комментарии t его путь вручную, это было бы значительное количество нажатий клавиш. У IDE есть служебные программы, которые делают это за вас (Eclipse is CTRL - /), а расширенные текстовые редакторы имеют макросы или, по крайней мере, вертикальные варианты.

Answer 6

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

Так что мой блок комментарии выглядеть следующим образом:

//***************************** 
// Some 
// Comments 
// Here 
//*****************************