Допустим, у вас есть:
if(condition) {
i = 1;
} else {
i = 2;
}
и вам нужно поместить комментарии, объясняющие блоки if и else. Какой самый читаемый способ сделать это, чтобы кто-то мог легко забрать их на первый взгляд?
Обычно я делаю это так:
//check for condition
if(condition) {
i = 1;
} else {
//condition isn't met
i = 2;
}
который я нахожу недостаточно хорошим, поскольку комментарии находятся на разных уровнях, поэтому быстро взгляните на комментарий if и комментарий else будет выглядеть так, как будто он принадлежит к некоторой внутренней структуре.
Поместите их так:
if(condition) {
//check for condition
i = 1;
} else {
//condition isn't met
i = 2;
}
не выглядит хорошо для меня, так как кажется, что вся структура не комментируется (условие может быть большим и принимать несколько строк).
Что-то вроде этого:
//check for condition
if(condition) {
i = 1;
//condition isn't met
} else {
i = 2;
}
будет, вероятно, лучшим стилем с точки зрения комментариев, но запутанным как структура кода.
Как вы комментируете такие блоки?
PS. Я не спрашиваю о реорганизации этих двух строк кода, только о стиле кода и форматировании комментариев.
Если необходимо прокомментировать if else, я предпочитаю описывать случай, из-за чего код достиг этой точки. Особенно в коде с высокой циклической сложностью
if (condition) {
// User is taking a course at college x:
i = 1;
} else {
// User is not taking any course at college x:
i = 2;
}
Другой вариант:
if(condition) { //check for condition
i = 1;
} else { //condition isn't met
i = 2;
}
Вы должны только комментировать, если код не является самоочевидным. Так что сделайте, если я объясню. Как это возможно
bool fooIsNotReallyGood = ....;
if(fooIsNotReallyGood) {
...
} else {
...
}
Если код уже не является самодокументированным, я бы структурировал его следующим образом:
if (someCondition) {
// If some condition, then do stuff 1.
doStuff1();
}
else {
// Else do stuff 2.
doStuff2();
}
Но опять же, это не имеет большого смысла, если код уже самодокументирован. Если вы хотите добавить комментарии из-за некоторого сложного состояния, например:
if (x == null || x.startsWith("foo") || x.endsWith("bar") || x.equals("baz")) {
doStuff1();
}
else {
doStuff2();
}
Тогда я решил бы реорганизовать его как:
boolean someCondition = (x == null || x.startsWith("foo") || x.endsWith("baz") || x.equals("waa");
if (someCondition) {
doStuff1();
} else {
doStuff2();
}
Здесь имя переменной someCondition фактически суммирует все условие в двух словах. Например. usernameIsValid, userIsAllowedToLogin или так.
Переходите к условиям самокомментации, тогда дополнительные комментарии не нужны. Предположим, что условие заключается в том, что максимальный кредит в стоимости достигнут. Это дает нам:
if (maximumLoanToValueIsReached)
{
i=1;
}
else
{
i=2;
}
Не нужно указывать, когда я = 2, что максимальная сумма кредита не была достигнута, поскольку это самообучение. В стороне, я также переименовал бы i в нечто более значимое.
Я бы не стал комментировать эти конкретные случаи вообще - комментарии не добавляют никакой ценности по вашему уже понятному коду. Если у вас очень сложное условие, которое трудно читать, я бы рассмотрел возможность его включения в функцию (возможно, inline) с очень чистым именем.
//condition isn't met кажется бесполезным комментарием. Но в случае, когда такой комментарий требуется, я делаю это так (С#):
//check for condition
if(condition)
{
i = 1;
}
//some other condition
else
{
i = 2;
}
Однако, если блок является только if-else, я бы объединил оба комментария раньше, если.
Для javascript я предпочитаю
//check for condition
if(condition) {
i = 1;
} else { //some other condition
i = 2;
}
P.S. Кажется, существует столько мнений, сколько есть людей:)
Вот как я делаю свои комментарии для if then statement, хотя обычно я считаю, что это не нужно. Мне нравится вставлять его в соответствие с if/else и вставлять вкладку в одно и то же место
if ( condition ) //if above the bar
{
i = 0;
k = 1;
}
else //else if below
{
i = 1;
k = 2;
}
Переменные важны, а не сами условия.
if condition: # <condition dependent variable> was <predicated>
dosomething()
elif othercondition: # <othercondition dependent variable> <predicated>
dootherthing()
else: # <all variables> <not predicated>
doelsething()
Нет единого ответа - у разных людей будут разные мнения о том, что наиболее читаемо. Тем не менее, я думаю, что есть согласие, что комментарии должны действительно добавить ценность для (в противном случае самоочевидного) кода и что стиль комментариев должен быть согласованным.
То, как я обрабатываю комментарии для не сразу понятных условий, выглядит следующим образом:
// If the condition for a local tree imbalance is met,
// juggle the immediate nodes to re-establish the balance.
// Otherwise, execute a global balancing pass.
if ( somewhat muddled condition )
{
...code...
}
else // Tree is in local balance
{
... more code...
} // if/else (tree locally imbalanced)
Комментарий к заключительному '}' существует прежде всего для того, чтобы дать концу условия более визуальный вес, чтобы облегчить чтение через источник.
Комментарии - это очень личное дело, и (как видно из некоторых предыдущих ответов) генерируют столько же дебатов, сколько и код.
В простых случаях комментарии отвлекают от кода. Но, предполагая более сложное условие, я предпочитаю:
/*
** Comment explaining what the condition
** is trying to determine
*/
if ( condition )
{
/*
** Comment explaining the implications
** of the condition being met
*/
do_something();
}
else
{
/*
** Comment explaining the implications
** of the condition not being met
*/
do_something_else();
}
В любом случае комментарии не должны просто повторять код.
Вы можете извлечь код if-else в методы и правильно их назвать:
function main() {
checkForCondition(condition);
conditionIsNotMet(condition);
}
function checkForCondition(boolean condition) {
if (condition) {
i = 1;
}
}
function conditionIsNotMet(boolean condition) {
if (!condition) {
i = 2;
}
}
В таком тривиальном случае это кажется излишним, но представьте, что имеет более одной строки на ветвь if-else.