Почему "//" многословный комментарий к файлу плохо (в Java)?

Ответ 1

На самом деле, я использовал // для нескольких строк в течение многих лет и никогда не испытывал серьезных проблем с этим. Я больше не поклонник /*...*/, потому что вы получаете:

/* I'm commenting out all this code for a moment
  ...
  /* And here is a multi line comment
     that was hidden in the middle */
  ...
*/ 

Спасибо компилятору, что он расстроен и говорит мне о проблеме.

Где как:

...
// And here is a multi line comment
// that was hidden in the middle
...

становится с одним макросом:

// ...
// // And here is a multi line comment
// // that was hidden in the middle
// ...

и счастливо обращается с другим единственным макросом, который возвращает его обратно в исходную форму

и для:

  // but now you have 
  // trouble edditing
  // your comments so
  // that every  line
  // is of equal size

Я говорю:

  // Tough, this is a piece of code not a 
  // published novel
  // and if varying lengths
  // make
  // it hard for you to read then heaven
  // forbid how you handle the code

И вы не ненавидите edditing:

/******************************************************************
 * Program: Foo.java                                              *
 ******************************************************************
 * Author:  Codey Art Work                                        *
 * Purpose: To do something with something and get something not  *
 *          forgetting something else.                            *
 ******************************************************************
 * Revision History:                                              *
 ******************************************************************
 *  Date  | Author |                                              *
 *--------|--------|----------------------------------------------*
 * 1/2/09 | Jack   | Now I have to keep all my comments in this   * 
 *        |        | tiny little space and if I edit it I just go *
 *        |        | aaarrrrrrggggggggggghhhhhhhhhhh!!!!!!!!!!!!! *
 ******************************************************************/

которые всегда появляются в местах, настаивающих на /* */ над //

<суб > И я просто хотел бы сказать ребятам из Stack Overflow, это действительно классный редактор. Выполнение примеров кода очень просто.

Ответ 2

Идея заключается в том, что многострочный текстовый комментарий - это один объект, который вы хотите логически поддерживать вместе. Разрывы строк в таком комментарии - не что иное, как места для обертывания текста, поэтому разбить его на многие "отдельные" комментарии не имеет смысла. Поэтому вы строите единый блок комментариев вокруг всего - используя /* */.

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

Ответ 3

Это делает модификацию и форматирование длинных комментариев чрезвычайно болезненными.

Большинство редакторов предоставляют некоторую возможность для переноса текста в строки с удобочитаемой длиной. Если каждая строка начинается с "//", они будут перемещены, а затем должны быть удалены, а новые - повторно вставлены. Все эти утомительные работы можно избежать, используя комментарии "/* */style".

Ответ 4

Даже комментирование большого количества кода с//иногда может быть довольно ужасным.

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

выберите большой блок кода, который уже содержит некоторый//многострочный код с комментариями, нажмите ctrl-/и прокомментируйте все это, затем сделайте ctrl-shift-f, чтобы отформатировать ваш код, если по какой-либо причине ваш форматтер имеет дело с комментариями он будет переформатировать ваш код. Затем переустановите все это и раскомментируйте его с помощью ctrl-/again...

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

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

/** для комментария Javadoc */таким образом комментарии доступны в полном объеме кода, документации и т.д. комментарий один раз, используйте везде.

Если вы знаете, что собираетесь создавать многострочный комментарий, который не является java-документом, а затем запускать его с помощью /*, IDE позаботится об остальном, насколько это касается форматирования. Поэтому, чтобы объяснить странные алгоритмы исправления в коде, я буду использовать /* */, а не //. Я сохраняю его для одиночного лайнера, когда это необходимо.

Мой 2 цента

Ответ 5

Я всегда думал, что комментарии для комментариев в формате * */style необходимы для многострочных комментариев, потому что//было разрешено "в нескольких последовательных строках для комментирования разделов кода". Инструменты форматирования кода должны иметь возможность легко отличать многострочные комментарии от кода с комментариями.

Если вы скажете инструменту форматирования кода (или вашей IDE) для очистки вашего файла, вы, скорее всего, захотите, чтобы он перевернул многострочные комментарии на поле, обертывая их в пространстве. Вы бы не то, что инструмент обернуть прокомментировал код таким образом.

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

Ответ 6

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

Честно говоря, я думаю, что это двойной стандарт с javadoc. Javadoc требует:

/**
 * Validates a chess move. Use {@link #doMove(int, int, int, int)} to move a piece.
 * 
 * @param theFromFile file from which a piece is being moved
 * @param theFromRank rank from which a piece is being moved
 * @param theToFile   file to which a piece is being moved
 * @param theToRank   rank to which a piece is being moved
 * @return            true if the chess move is valid, otherwise false
 */

и я не понимаю, почему повторяющийся "*" лучше, чем "//". Итак, для меня нет ничего плохого в том, что//плохое (потому что редакторы могут быть настроены для автоматического добавления их в многострочные комментарии) и просто конвенция и обычная практика.

Ответ 7

может быть для форматирования кода... если вы сделали автоматическое форматирование (отступы), коды выглядят уродливыми.

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

Ответ 8

По моему опыту, следующие стили комментариев иллюстрируют, почему я согласен с соглашениями Java Code.

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

/**
 * Description
 * @param foo refers to ...
 * @return true if...
 */

Комментарии на английском языке

/*
 * The sole reason for this unorthodox construct is just
 * to ...
 */
 synchronized(lockObject) {
     foo = bar;
 }

или

/* This is a single line comment */

Комментарий кода (я не хочу проверять код с комментариями).

// /* Accumulate the results */
// for (int i = 0; i < 10; i+=1) {
//     bar += result[i];
// }

Почему?

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

  // This is a 
  // long broken up comment that has been edited multiple
  // times
  // and the developer was too lazy to fix the justification

или вы должны исправить это обоснование вручную.

Вы не хотите, чтобы Eclipse перезапускал код с комментариями, поэтому используйте //

Во-вторых, вы можете выделить блок кода и добавить и удалить//комментарии стиля к началу каждой строки.

Примечание. Я всегда начинаю каждую строку комментария блока с помощью *. Следующее просто вызывает проблемы:

/* Accumulate the results */
/*
for (int i = 0; i < 10; i+=1) {
    /* comment broke the outer comment : Sigh! */ 
    bar += result[i];
}
*/