Является ли определение переменной для именования аргумента метода хорошей практикой?

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

var preventUndo = true;
doSomething(preventUndo);

Короче версия этого к этому будет,

doSomething(true);

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

Объясняя переменные

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

Код хорошего качества сообщает о намерениях читателю; и как профессиональный разработчик удобочитаемость и удобство обслуживания являются вашими целями # 1.

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

editButton.Enabled = (_grid.SelectedRow != null && ((Person)_grid.SelectedRow).Status == PersonStatus.Active);

по сравнению с немного дольше, но, возможно, яснее:

bool personIsSelected = (_grid.SelectedRow != null);
bool selectedPersonIsEditable = (personIsSelected && ((Person)_grid.SelectedRow).Status == PersonStatus.Active)
editButton.Enabled = (personIsSelected && selectedPersonIsEditable);

Булевы параметры

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

ParseFolder(true, false);

Вы должны посмотреть, что означают эти параметры; если бы они были перечислениями, было бы намного яснее:

ParseFolder(ParseBehaviour.Recursive, CompatibilityOption.Strict);

Редактировать:

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

Не пишите код, который вам не нужен.

Если вам doSomething(true)трудно понять, вы должны добавить комментарий:

// Do something and prevent the undo.
doSomething(true);

или, если язык поддерживает это, добавьте имя параметра:

doSomething(preventUndo: true);

В противном случае положитесь на вашу среду IDE, чтобы получить подпись вызванного метода:

Случаи, когда это полезно

Помещение дополнительной переменной может быть полезно:

1. Для целей отладки:

   var productId = this.Data.GetLastProductId();
   this.Data.AddToCart(productId);
   

   Один и тот же код может быть записан в одну строку, но если вы хотите установить точку останова перед добавлением товара в корзину, чтобы проверить правильность идентификатора продукта, лучше написать две строки вместо одной.

2. Если у вас есть метод с большим количеством параметров, и каждый параметр идет из оценки. В одной строке это может стать совершенно нечитаемым.

   // Even with indentation, this is unreadable.
   var doSomething(
       isSomethingElse ? 0 : this.getAValue(),
       this.getAnotherOne() ?? this.default,
       (a + b + c + d + e) * f,
       this.hello ? this.world : (this.hello2 ? this.world2 : -1));
   

3. Если оценка параметра слишком сложна. Пример кода, который я видел:

   // Wouldn't it be easier to have several if/else's (maybe even in a separate method)?
   do(something ? (hello ? world : -1) : (programmers ? stackexchange : (com ? -1 : 0)));
   

Почему не в других случаях?

Почему бы вам не создать дополнительные переменные в простых случаях?

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

2. Но из-за риска диссоциации имени вы дадите переменной имя параметра.

   Пример:

   Допустим, оригинальный код:

   void doSomething(bool preventUndo)
   {
       // Does something very interesting.
       undoHistory.removeLast();
   }
   
   // Later in code:
   var preventUndo = true;
   doSomething(preventUndo);
   

   Позже, разработчик, работающий над doSomethingзамечаниями, которые недавно, история отмены представил два новых метода:

   undoHistory.clearAll() { ... }
   undoHistory.disable() { ... }
   

   Теперь, preventUndoкажется, не очень понятно. Значит ли это, что будет предотвращено только последнее действие? Или, может быть, это означает, что пользователь больше не сможет использовать функцию отмены? Или что история отмен будет очищена? Более понятные имена будут:

   doSomething(bool hideLastUndo) { ... }
   doSomething(bool removeAllUndo) { ... }
   doSomething(bool disableUndoFeature) { ... }
   

   Итак, теперь у вас есть:

   void doSomething(bool hideLastUndo)
   {
       // Does something very interesting.
       undoHistory.removeLast();
   }
   
   // Later in code, very error prone, while the signature of the method is clear:
   var preventUndo = true;
   doSomething(preventUndo);
   

Как насчет перечислений?

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

enum undoPrevention
{
    keepInHistory,
    prevent,
}

void doSomething(undoPrevention preventUndo)
{
    doTheJob();
    if (preventUndo == undoPrevention.prevent)
    {
        this.undoHistory.discardLastEntry();
    }
}

doSomething(undoPrevention.prevent);

Проблемы с этим:

1. Это слишком много кода. if (preventUndo == undoPrevention.prevent)? Шутки в сторону?! Я не хочу писать такие ifкаждый раз.

2. Добавление элемента в перечисление очень заманчиво позже, если я использую то же самое перечисление где-нибудь еще. Что, если я изменю это так:

   enum undoPrevention
   {
       keepInHistory,
       prevent,
       keepButDisable, // Keeps the entry in the history, but makes it disabled.
   }
   

   Что теперь будет? Будет ли doSomethingметод работать так, как ожидалось? Чтобы предотвратить это, потребуется написать этот метод с самого начала так:

   void doSomething(undoPrevention preventUndo)
   {
       if (![undoPrevention.keepInHistory, undoPrevention.prevent].contains(preventUndo))
       {
           throw new ArgumentException('preventUndo');
       }
   
       doTheJob();
       if (preventUndo == undoPrevention.prevent)
       {
           this.undoHistory.discardLastEntry();
       }
   }
   

   Вариант, который использует логические выражения, начинает выглядеть так красиво!

   void doSomething(bool preventUndo)
   {
       doTheJob();
       if (preventUndo)
       {
           this.undoHistory.discardLastEntry();
       }
   }
   

Также вы не должны писать методы с логическими флагами.

Цитируя Роберта К. Мартина, он говорит в своей книге «Чистый код» (ISBN-13 978-0-13-235088-4): «Передавать логическое значение в функцию - это действительно ужасная практика».

Перефразируя его, рассуждение состоит в том, что тот факт, что у вас есть переключатель истина / ложь, означает, что ваш метод, скорее всего, выполняет две разные вещи (например, «Делать что-то с отменой» и «Делать что-то без отмены») и поэтому должен быть разделить на два разных метода (которые могут вызывать одно и то же).

DoSomething()
{...

DoSomethingUndoable()
{....

Когда вы посмотрите на два класса, чтобы увидеть, насколько они связаны, одна из категорий - это соединение данных , которое относится к коду в одном классе, вызывающему методы другого класса и просто передающему данные, например, за какой месяц вы хотите получить отчет, а другой Категория - это управление связью , вызов методов и передача чего-то, что управляет поведением метода. Пример, который я использую в классе - это verboseфлаг или reportTypeфлаг, но preventUndoэто также отличный пример. Как вы только что продемонстрировали, связывание управления затрудняет чтение кода вызова и понимание происходящего. Это также делает вызывающий код уязвимым к изменениям, doSomething()которые используют один и тот же флаг для управления отменой и архивированием, или добавляют другой параметр вdoSomething() контролировать архивирование, таким образом нарушая ваш код и так далее.

Проблема в том, что код слишком тесно связан. Передача bool для контроля поведения, по моему мнению, является признаком плохого API. Если у вас есть API, измените его. Два метода, doSomething()и doSomethingWithUndo(), было бы лучше. если вы не владеете им, напишите два метода-обертки самостоятельно в собственном коде, и пусть один из них вызовет, doSomething(true)а другой вызовет doSomething(false).

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

Переменная должна быть названа в честь их роли в текущей области видимости. Не Объем, куда они отправлены.

В JavaScript я бы сделал так, чтобы функция принимала объект в качестве единственного параметра, примерно так:

function doSomething(settings) {
    var preventUndo = settings.hasOwnProperty('preventUndo') ? settings.preventUndo : false;
    // Deal with preventUndo in the normal way.
}

Затем позвоните с помощью:

doSomething({preventUndo: true});

Я люблю использовать возможности языка, чтобы помочь ясности сам. Например, в C # вы можете указать параметры по имени:

 CallSomething(name: "So and so", age: 12, description: "A random person.");

В JavaScript я обычно предпочитаю использовать объект параметров в качестве аргумента по этой причине:

function doSomething(args) { /*...*/ }

doSomething({ name: 'So and so', age: 12, description: 'A random person.' });

Это только мое предпочтение, хотя. Я полагаю, что это будет сильно зависеть от вызываемого метода и от того, как IDE поможет разработчику понять сигнатуру.

Я считаю, что это самый простой и легкий для чтения:

enum Undo { ALLOW, PREVENT }

doSomething(Undo u) {
    if (Undo.ALLOW == u) {
        // save stuff to undo later.
    }
    // do your thing
}

doSomething(Undo.ALLOW);

MainMa это не нравится. Возможно, нам придется согласиться не соглашаться или мы можем использовать решение, которое предлагает Джошуа Блох:

enum Undo {
    ALLOW {
        @Override
        public void createUndoBuffer() {
            // put undo code here
        }
    },
    PREVENT {
        @Override
        public void createUndoBuffer() {
            // do nothing
        }
    };

    public abstract void createUndoBuffer();
}

doSomething(Undo u) {
    u.createUndoBuffer();
    // do your thing
}

Теперь, если вы когда-нибудь добавите Undo.LIMITED_UNDO, ваш код не скомпилируется, если вы не реализуете метод createUndoBuffer (). А в doSomething () нет if (Undo.ALLOW == u). Я сделал это обоими способами, и второй метод довольно тяжелый и немного сложный для понимания, когда перечисление Undo распространяется на страницы и страницы кода, но это заставляет задуматься. Я обычно придерживаюсь более простого метода, чтобы заменить простое логическое значение на 2-значное перечисление, пока у меня не появится причина для изменения. Когда я добавляю третье значение, я использую свою IDE для «Find-usages» и исправляю все тогда.

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

Я могу думать о двух альтернативах, которые не включают дополнительную переменную:

1. Используйте дополнительный комментарий

doSomething(/* preventUndo */ true);

2. Используйте двухзначное перечисление вместо логического

enum Options
{
    PreventUndo,
    ...
}

...

doSomething(PreventUndo);

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

РЕДАКТИРОВАТЬ

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

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

if (preventUndo)
{
    ...
}

у вас есть

if (undoOption == PreventUndo)
{
    ...
}

или же

switch (undoOption)
{
  case PreventUndo:
  ...
}

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

Я согласен с тем, что @GlenPeterson сказал:

doSomething(Undo.ALLOW); // call using a self evident enum

но интересным было бы следующее, так как мне кажется, что есть только две возможности (истинные или ложные)

//Two methods    

doSomething()  // this method does something but doesn't prevent undo

doSomethingPreventUndo() // this method does something and prevents undo

Поскольку вы спрашиваете в основном о javascript, используя coffeescript, вы можете получить именованный аргумент, такой как синтаксис, очень просто:

# declare method, ={} declares a default value to prevent null reference errors
doSomething = ({preventUndo} = {}) ->
  if preventUndo
    undo = no
  else
    undo = yes

#call method
doSomething preventUndo: yes
#or 
doSomething(preventUndo: yes)

компилируется в

var doSomething;

doSomething = function(_arg) {
  var preventUndo, undo;
  preventUndo = (_arg != null ? _arg : {}).preventUndo;
  if (preventUndo) {
    return undo = false;
  } else {
    return undo = true;
  }
};

doSomething({
  preventUndo: true
});

doSomething({
  preventUndo: true
});

Повеселитесь на http://js2coffee.org/, чтобы попробовать возможности

Просто для менее традиционного решения, и поскольку OP упомянул Javascript, можно использовать ассоциативный массив для отображения значений. Преимущество перед единственным логическим значением заключается в том, что вы можете иметь столько аргументов, сколько захотите, и не беспокоиться об их последовательности.

var doSomethingOptions = new Array();

doSomethingOptions["PREVENTUNDO"] = true;
doSomethingOptions["TESTMODE"] = false;

doSomething( doSomethingOptions );

// ...

function doSomething( doSomethingOptions ){
    // Check for null here
    if( doSomethingOptions["PREVENTUNDO"] ) // ...
}

Я понимаю, что это рефлекс кого-то со строго типизированным фоном, и он может быть не очень практичным, но считаю это оригинальностью.

Другая возможность состоит в том, чтобы иметь объект, и это также возможно в Javascript. Я не уверен на 100%, что это правильно. Взгляните на шаблоны, такие как Фабрика для дальнейшего вдохновения.

function SomethingDoer( preventUndo ) {
    this.preventUndo = preventUndo;
    this.doSomething = function() {
            if( this.preventUndo ){
                    // ...
            }
    };
}

mySomethingDoer = new SomethingDoer(true).doSomething();

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

Я думаю, что полезно отметить, что эта проблема в основном предотвращается, когда язык программирования поддерживает именованные аргументы / ключевые слова-аргументы, как в C # 4 и Python, или когда аргументы метода чередуются в имени метода, как в Smalltalk или Objective-C.

Примеры:

// C# 4
foo.doSomething(preventUndo: true);

# Python
foo.doSomething(preventUndo=True)

// Objective-C
[foo doSomethingWith:bar shouldPreventUndo:YES];

Следует избегать передачи логических переменных в качестве аргументов функциям. Потому что функции должны делать одну вещь за раз. Передав логическую переменную, функция получила два поведения. Это также создает проблему читабельности на более позднем этапе или для других программистов, которые склонны видеть ваш код. Это также создает проблему при тестировании функции. Вероятно, в этом случае вам нужно создать два теста. Представьте, что если у вас есть функция, у которой есть оператор switch и она меняет свое поведение в зависимости от типа переключателя, то для вас должно быть определено так много различных тестовых случаев.

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

int preventUndo = true;
doSomething(preventUndo);

Хороший компилятор для языков низкого уровня, таких как C ++, оптимизирует машинный код выше 2 строк, как показано ниже:

doSomething(true); 

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

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