Позиционирование комментариев относительно кода

Question

Каков наилучший способ для размещения комментариев в коде? Я вижу, по крайней мере, три различные способа:

1: 
int i = 10;  //Set i to 10 

2: 
//Set i to 10 
int i = 10; 

3: 
int i = 10; 
//Set i to 10 

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

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

Answer 1

Вариант 3 Это просто неправильно. Все инструменты, которые я знаю, ждут метод docs перед тем, как использовать метод, подобный в 2. Таким образом, противоположное внутри метода запутывает.

В противном случае, 1 & 2 оба нормально, но я использовал только 1 на коротких строках кода. Как правило, 2 будет моим предпочтительным вариантом, потому что он не только согласуется с комментариями для методов/классов, вы видите комментарий до.

Answer 2

Ну, должно быть очень мало комментариев этой формы - если вы обнаружите, что комментируете отдельные заявления, что-то не так. Сказав это, у меня не было бы проблем с №1 или №2 - я никогда не видел №3 и не хочу.

Answer 3

Я иду в первую очередь для выше - с пустой строкой над комментарием, поэтому он явно ссылается на код ниже, а не на что-то еще.

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

Answer 4

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

Если он не может, вы должны использовать опцию No 2, потому что это помогает держать шорцев строки в редакторе кода

Answer 5

Я бы сказал, что вы должны использовать 1: для одной строки комментариев, то есть, когда вы хотите что-то объяснить, что не очевидна в одной строке, и если строка достаточно коротка, чтобы комментарий соответствовал этой строке, длина строки не превышала 80 символов, тогда 2: должно быть в порядке.

Использование 2: для комментирования более длинный блок, т.е. пытается объяснить алгоритм или декодирования и т.д.

Не используйте 3: вообще.

Answer 6

Предлагаю прочитать главу 32: Самодокументирующий код в коде завершен.

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

Answer 7

я люблю следующую форму для коротких комментариев

blah; // comment 

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

Answer 8

Я лично предпочитаю опцию .Вариант в порядке, если комментарий достаточно короткий и содержит некоторую необходимую информацию.

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

Answer 9

Я использую определенный тип для Javadoc (очевидно):

/** 
* This is a Javadoc comment. 
*/ 

И я иду с лайнерами в сочетании с пробелами в коде:

// This comment refers to 
someGroupingOfCode(); 
thatPerforms(aCertainTask); 
whichIsThenFollowedBy(anEmptyLine); 

// And possibly another comment 
thatGoesWith(); 
theNextGroupOfTasks(); 

И для заявлений я вообще делать:

int i; // This stores the value of your eye 
File x; // XXX directory location 

Что касается использования вкладок в последнем примере, я даже не собираюсь туда идти. Не хочется бросать бензин на огонь прямо сейчас. :)