Правильний коментар для булевих аргументів функції, які є "помилковими"?

З деяких проектів з відкритим кодом я зібрав такий стиль кодування

void someFunction(bool forget);

void ourFunction() {
  someFunction(false /* forget */);
}    

Я завжди сумніваюся, що falseтут означає. Чи означає це "забути", чи "забудь" посилається на відповідний параметр (як у випадку вище), а "помилка" має намір заперечувати його?

Який стиль використовується найчастіше і який найкращий спосіб (або які кращі способи) уникнути неоднозначності?

У зразковому коді, який ви опублікували, він виглядає як forgetаргумент прапора. (Я не можу бути впевнений, оскільки функція суто гіпотетична.)

Аргументи прапорця - це запах коду. Вони вказують, що функція виконує більше однієї речі, а хороша функція повинна виконувати лише одне.

Щоб уникнути аргументу прапорця, розділіть функцію на дві функції, які пояснюють різницю в назві функції.

Аргумент прапора

serveIceCream(bool lowFat)

Немає аргументу прапор

serveTraditionalIceCream()
serveLowFatIceCream()

редагувати: В ідеалі взагалі не потрібно тримати функцію з параметром прапора. Існують випадки того, що Фоулер називає заплутану реалізацію, де повністю розділення функцій створює дублюваний код. Однак чим вища цикломатична складність параметризованої функції, тим сильнішим є аргумент для її позбавлення.

Словами мирянина:

• false є буквальним.
• ви переходите буквальне false
• ви говорите someFunctionне забувати
• ви говорите, someFunctionщо параметр забуття єfalse
• ви говорите someFunctionпам'ятати

На мою думку, було б краще, якби функція була такою:

void someFunction(bool remember);

ви можете це назвати

void ourFunction() {
  someFunction(true);
} 

або збережіть стару назву, але змініть функцію обгортки на

void ourFunctionWithRemember() {
  someFunction(false);
} 

Редагувати:

Як заявив @Vorac, завжди прагніть використовувати позитивні слова. Подвійне заперечення заплутано.

Параметр може бути добре названий; важко сказати, не знаючи назви функції. Я припускаю, що коментар був написаний оригінальним автором функції, і це було нагадуванням про те, що переходить falseу someFunctionзасоби, але для тих, хто піде потім, на перший погляд це трохи незрозуміло.

Використання позитивної назви змінної (запропонованої у Code Complete ) може бути найпростішою зміною, яка полегшить читання цього фрагмента, наприклад,

void someFunction(boolean remember);

потім ourFunctionстає:

void ourFunction() {
    someFunction(true /* remember */);
}

Однак використання enum робить виклик функції ще простішим для розуміння за рахунок деякого підтримуючого коду:

public enum RememberFoo {
    REMEMBER,
    FORGET
}

...

void someFunction(RememberFoo remember);

...

void ourFunction() {
    someFunction(RememberFoo.REMEMBER);
}

Якщо ви не можете змінити підпис з someFunctionбудь-якої причини, використання тимчасової змінної полегшує також читання коду, на зразок спрощення умовних умов, вводячи змінну не з іншої причини, як полегшити розбір коду людьми. .

void someFunction(boolean remember);

...

void ourFunction() {
    boolean remember = false;
    someFunction(remember);
}

Перейменуйте змінну, щоб значення bool має сенс.

Це в мільйон разів краще, ніж додавати коментар для пояснення аргументів функції, оскільки назва неоднозначна.

Створіть локальний булева з більш описовою назвою та призначте їй значення. Таким чином сенс буде більш зрозумілим.

void ourFunction() {
    bool takeAction = false;  /* false means to forget */
    someFunction( takeAction );
}    

Якщо ви не можете перейменувати змінну, коментар повинен бути трохи виразнішим:

void ourFunction() {
    /* false means that the method should forget what was requested */
    someFunction( false );
}    

Є добра стаття, в якій згадується така точна ситуація, оскільки вона посилається на API Qt-Style. Там його називають «Лолова пара булевих параметрів», і його варто прочитати.

Суть її полягає в:

1. Перевантаження функції так, що не потрібен bool, краще
2. Використання переліків (як пропонує Есаїлія) найкраще

Це химерний коментар.

З точки зору компілятора, someFunction(false /* forget */);насправді someFunction(false);(коментар знятий). Отже, все, що робить цей рядок, - це виклик someFunctionз першим (і єдиним) аргументом, встановленим на false.

/* forget */- це лише назва параметра. Це, мабуть, не що інше, як швидке (і брудне) нагадування, що насправді не потрібно там бути. Просто використовуйте менш неоднозначне ім'я параметра, і коментар вам взагалі не знадобиться.

Один із порад чистого коду - мінімізувати кількість зайвих коментарів ¹ (оскільки вони, як правило, гниють), і правильно називати функції та методи.

Після цього я просто видалю коментар. Зрештою, сучасні IDE (на зразок затемнення) з'являють вікно з кодом, коли ви кладете мишу над функцією. Побачення коду повинно усунути неоднозначність.

¹ Коментувати складний код - це нормально.

Для відношення очевидних, коментарі можуть брехати. Таким чином, завжди краще , щоб зробити ваш код самодокументіруемимі , не вдаючись до коментарів пояснити, бо який - то людина (можливо , ви) зміниться trueна , falseа не оновлювати свій коментар.

Якщо ви не можете змінити API, я вдаюсь до двох варіантів

• Змініть коментар, щоб він завжди був вірним, незалежно від коду. Якщо ви зателефонували лише один раз, це хороше рішення, оскільки він зберігає документацію локально.

     someFunction (false / * true = забути, false = запам'ятати * /); `

• Використовуйте #defines, особливо якщо ви називаєте його не раз.

     #define ЗАБЕЗПЕЧЕНО правда
     #define ПАМ'ЯТИ помилково
     деякіфункції (ПАМ'ЯТЬСЯ);

мені подобається що відповідь про те, щоб коментар завжди був правдивим , але, хоча добре, я думаю, що він не вистачає основної проблеми з цим кодом - він називається буквально.

Ви повинні уникати використання літералів під час виклику методів. Локальні змінні, необов'язкові параметри, названі параметри, перерахунки - те, як ви найкраще їх уникнути, залежатиме від мови та наявних, але намагайтеся їх уникати. Літерали мають значення, але вони не мають значення.

У C # я використовував названі параметри, щоб зробити це зрозумілішим

someFunction(forget: false);

Або enum:

enum Memory { Remember, Forget };

someFunction(Memory.Forget);

Або перевантаження:

someFunctionForget();

Або поліморфізм`:

var foo = new Elephantine();

foo.someFunction();

Іменування завжди повинно вирішувати неоднозначність для булів. Я завжди називаю булеве щось на зразок "isThis" або "shouldDoThat", наприклад:

void printTree(Tree tree, bool shouldPrintPretty){ ... }

і так далі. Але коли ви посилаєтесь на чужий код, найкраще просто залишати коментар при передачі значень.