Правильный комментарий для аргументов логической функции, которые являются «ложными»?

Из некоторых проектов с открытым исходным кодом я собрал следующий стиль кодирования

void someFunction(bool forget);

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

Я всегда сомневаюсь, что falseздесь значит. Означает ли это «забыть», или «забыть» относится к соответствующему параметру (как в случае выше), а «ложь» означает его отрицание?

Какой стиль используется чаще всего, и как лучше (или некоторые из лучших способов) избежать двусмысленности?

В приведенном вами примере кода это выглядит как forgetаргумент флага. (Я не могу быть уверен, потому что функция является чисто гипотетической.)

Аргументы флагов - это запах кода. Они указывают, что функция делает больше, чем одну вещь, а хорошая функция должна делать только одну вещь.

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

Флаг аргумента

serveIceCream(bool lowFat)

Нет аргумента флага

serveTraditionalIceCream()
serveLowFatIceCream()

редактировать: в идеале, вам не нужно вообще обходить функцию с параметром flag. Существуют случаи, аналогичные тому, что Фаулер называет запутанной реализацией, когда полное разделение функций создает дублированный код. Однако чем выше цикломатическая сложность параметризованной функции, тем сильнее аргумент для ее избавления.

По словам непрофессионала:

• 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. Лучше всего использовать enum (как предлагает Esailija)

Это странный комментарий.

На someFunction(false /* forget */);самом деле, с точки зрения компилятора someFunction(false);(комментарий удаляется). Итак, все, что делает эта строка, это вызов someFunctionс первым (и единственным) аргументом, установленным в false.

/* forget */это просто имя параметра. Это, вероятно, не более чем быстрое (и грязное) напоминание, которое на самом деле не должно быть там. Просто используйте менее двусмысленное имя параметра, и вам вообще не понадобится комментарий.

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

После этого я бы просто удалил комментарий. В конце концов, современные IDE (например, eclipse) выдают окно с кодом, когда вы наводите курсор мыши на функцию. Увидев код, следует убрать неоднозначность.

¹ Комментировать некоторый сложный код - это нормально.

Чтобы отметить очевидное, комментарии могут лгать. Таким образом, всегда лучше , чтобы сделать ваш код самодокументируемыми , не прибегая к комментариям объяснить, потому что какой - то человек (возможно , вы) изменится trueна , falseа не обновлять свой комментарий.

Если вы не можете изменить API, то я прибегаю к 2 вариантам

• Измените комментарий, чтобы он всегда был верным, независимо от кода. Если вы называете это только один раз, это хорошее решение, поскольку документ остается локальным.

     someFunction (false / * true = забыть, false = запомнить * /); `

• Используйте #defines, особенно если вы вызываете его более одного раза.

     #define FORGET true
     #define REMEMBER false
     SomeFunction (REMEMBER);

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

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

В 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){ ... }

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