Вкажіть необов'язкові імена параметрів, хоча вони не потрібні?

Розглянемо наступний метод:

public List<Guid> ReturnEmployeeIds(bool includeManagement = false)
{

}

І наступний дзвінок:

var ids = ReturnEmployeeIds(true);

Для нового розробника в системі було б досить складно здогадатися, що trueзробив. Перше, що ви зробите, - навести курсор на ім'я методу або перейти до визначення (жодне з яких не є великими завданнями). Але, для читабельності, чи є сенс писати:

var ids = ReturnEmployeeIds(includeManagement: true);

Чи є де-небудь, що офіційно обговорює, чи слід чітко вказати необов'язкові параметри, коли компілятору вам не потрібно?

У наступній статті йдеться про деякі умови кодування: https://msdn.microsoft.com/en-gb/library/ff926074.aspx

Щось подібне до статті вище було б чудово.

Я б сказав, що в світі C # перерахунок був би одним із найкращих варіантів.

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

public enum WhatToInclude
{
    IncludeAll,
    ExcludeManagement
}

var ids = ReturnEmployeeIds(WhatToInclude.ExcludeManagement);

Отже, на мою думку тут:

enum> необов'язковий enum> необов'язковий bool

Редагувати: Зважаючи на обговорення з LeopardSkinPillBoxHat нижче щодо [Flags]перерахунку, який у цьому конкретному випадку може бути вдалим (оскільки ми конкретно говоримо про включення / виключення речей), я замість цього пропоную використовувати ISet<WhatToInclude>як параметр.

Це більш "сучасна" концепція з кількома перевагами, яка головним чином випливає з того, що вона входить до сімейства колекцій LINQ, але також [Flags]має 32 групи. Основним недоліком використання ISet<WhatToInclude>є те, як погано підтримуються набори в синтаксисі C #:

var ids = ReturnEmployeeIds(
    new HashSet<WhatToInclude>(new []{ 
        WhatToInclude.Cleaners, 
        WhatToInclude.Managers});

Деякі з них можуть бути пом’якшені допоміжними функціями, як для створення набору, так і для створення "наборів ярликів", таких як

var ids = ReturnEmployeeIds(WhatToIncludeHelper.IncludeAll)

чи є сенс писати:

 var ids=ReturnEmployeeIds(includeManagement: true);

Дискусійним є те, якщо це "хороший стиль", але IMHO це як мінімум не поганий стиль і корисний, доки рядок коду не стане "занадто довгим". Без названих параметрів також є загальним стилем введення пояснювальної змінної:

 bool includeManagement=true;
 var ids=ReturnEmployeeIds(includeManagement);

Цей стиль, мабуть, більш поширений серед програмістів на C #, ніж названий варіант параметра, оскільки названі параметри не були частиною мови до версії 4.0. Ефект від читабельності майже однаковий, просто потрібен додатковий рядок коду.

Тож моя рекомендація: якщо ви думаєте, що використання enum або двох функцій з різними іменами є "overkill", або ви не хочете або не можете змінити підпис з іншої причини, продовжуйте користуватися названим параметром.

Якщо ви стикаєтесь з таким кодом:

public List<Guid> ReturnEmployeeIds(bool includeManagement = false)
{

}

Ви можете майже гарантувати, що всередині {}заповіту буде щось на кшталт:

public List<Guid> ReturnEmployeeIds(bool includeManagement = false)
{
    if (includeManagement)
        return something
    else
        return something else
}

Іншими словами, булевий використовується для вибору між двома напрямами дії: метод має два обов'язки. Це майже гарантовано кодовий запах . Ми завжди повинні прагнути до того, щоб методи виконували лише одне; вони несуть лише одну відповідальність. Тому я б стверджував, що обидва ваші рішення - це неправильний підхід. Використання необов'язкових параметрів є ознакою того, що метод робить більше, ніж одне. Булеві параметри також є ознакою цього. Маючи обоє, обов'язково слід встановити дзвінок сигналізації. Тому ви повинні зробити це рефакторинг двох різних наборів функціональності на два окремі методи. Дайте назви методів, які дозволяють зрозуміти, що вони роблять, наприклад:

public List<Guid> GetNonManagementEmployeeIds()
{

}

public List<Guid> GetAllEmployeeIds()
{

}

Це як покращує читабельність коду, так і забезпечує кращий дотримання принципів SOLID.

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

У такому випадку, чи слід вводити ім'я параметра, навіть якщо компілятор цього не потребує? Я б припустив, що на це немає простої відповіді, і це судження потрібно для кожного конкретного випадку:

• Аргументом для визначення імені є те, що інші розробники (включаючи себе через півроку) повинні бути основною аудиторією вашого коду. Укладач, безумовно, другорядна аудиторія. Тому завжди пишіть код, щоб іншим людям було легше читати; а не просто постачати те, що потрібно компілятору. Прикладом того, як ми використовуємо це правило щодня, є те, що ми не заповнюємо наш код змінними _1, _2 тощо, ми використовуємо значущі імена (що не означають нічого для компілятора).
• Протилежним аргументом є те, що приватні методи - це деталі реалізації. Можна з розумом очікувати, що хтось, дивлячись на такий метод, як нижче, простежить через код, щоб зрозуміти призначення булевого параметра, оскільки вони знаходяться всередині внутрішнього коду:

public List<Guid> GetNonManagementEmployeeIds()
{
    return ReturnEmployeeIds(true);
}

Чи є вихідний файл та методи невеликими та легко зрозумілими? Якщо так, то названий параметр, ймовірно, становить шум. Якщо ні, це може бути дуже корисно. Тому застосовуйте правило відповідно до обставин.

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

Так, правда. Самодокументування коду - прекрасна річ. Як вказували інші відповіді, існують способи усунути неоднозначність виклику ReturnEmployeeIdsза допомогою enum, різних назв методів тощо. Однак іноді справді не вдається уникнути справи, але ви не хочете виходити з ладу та використовувати їх скрізь (якщо вам не подобається багатослівність візуального основного).

Наприклад, це може допомогти уточнити один дзвінок, але не обов'язково інший.

Тут може бути корисний названий аргумент:

var ids = ReturnEmployeeIds(includeManagement: true);

Не додайте додаткової ясності (я думаю, що це розбір перерахунку):

Enum.Parse(typeof(StringComparison), "Ordinal", ignoreCase: true);

Це може насправді знизити ясність (якщо людина не розуміє, що є у списку):

var employeeIds = new List<int>(capacity: 24);

Або де це не має значення, оскільки ви використовуєте хороші імена змінних:

bool includeManagement = true;
var ids = ReturnEmployeeIds(includeManagement);

Чи є де-небудь, що офіційно обговорює, чи слід чітко вказати необов'язкові параметри, коли компілятору вам не потрібно?

Не AFAIK. Давайте ж розглянемо обидві частини: єдиний час, коли вам потрібно явно використовувати названі параметри, це тому, що компілятор вимагає від вас цього (як правило, це видалити неоднозначність оператора). Тож крім цього, ви можете їх використовувати коли завгодно. У цій статті від MS є кілька пропозицій щодо того, коли ви, можливо, захочете їх використовувати, але це не особливо остаточно https://msdn.microsoft.com/en-us/library/dd264739.aspx .

Особисто я вважаю, що я їх використовую найчастіше, коли я створюю власні атрибути або закладаю новий метод, коли мої параметри можуть змінюватися або упорядковуватися (b / c названі атрибути можуть бути перелічені в будь-якому порядку). Крім того, я використовую їх лише тоді, коли надаю статичне значення в рядку, інакше, якщо я передаю змінну, я намагаюся використовувати хороші імена змінних.

TL; DR

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

Якщо параметр очевидний з (повністю кваліфікованого) імені методи , і це існування природно , що метод повинен робити, ви повинні НЕ використовувати іменований синтаксис параметрів. Наприклад, вReturnEmployeeName(57) цьому досить прочесно, що 57це ідентифікатор працівника, тому зайве коментувати його синтаксисом названого параметра.

Як ReturnEmployeeIds(true), як ви вже говорили, якщо ви не подивитеся на декларацію / документацію функції, неможливо зрозуміти, що trueозначає - так ви повинні використовувати синтаксис названого параметра.

Тепер розглянемо цей третій випадок:

void PrintEmployeeNames(bool includeManagement) {
    foreach (id; ReturnEmployeeIds(includeManagement)) {
        Console.WriteLine(ReturnEmployeeName(id));
    }
}

Синтаксис названого параметра тут не використовується, але оскільки ми передаємо змінну ReturnEmployeeIds, і ця змінна має ім'я, і ​​це ім'я означає те саме, що і параметр, до якого ми передаємо його (це часто так - але не завжди!) - нам не потрібен синтаксис названого параметра, щоб зрозуміти його значення з коду.

Отже, правило просте - якщо ви можете легко зрозуміти з виклику методу лише те, що повинен означати параметр, не використовуйте названий параметр. Якщо ви не можете - це недолік у читанні коду, і ви, ймовірно, хочете виправити це (звичайно, не за будь-яку ціну, але зазвичай ви хочете, щоб код був читабельним). Виправлення не обов'язково називати параметрами - ви також можете поставити значення в першу чергу або використовувати методи, запропоновані в інших відповідях, - поки кінцевий результат полегшує розуміння того, що робить параметр.

Так, я думаю, що це гарний стиль.

Це має найбільше значення для булевих і цілих констант.

Якщо ви передаєте змінну, ім'я змінної повинно робити значення зрозумілим. Якщо це не так, вам слід дати кращому імені.

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

Звичайно, не всі рядки очевидні. Якщо я бачу GetFooData ("M"), якщо я не знаю функцію, я поняття не маю, що означає "M". Якщо це якийсь код, наприклад, M = "співробітники на рівні управління", то, ймовірно, нам слід мати перерахунок, а не буквальний, а назва enum має бути чітким.

І я вважаю, що рядок може ввести в оману. Можливо, "Орегон" у моєму прикладі вище стосується не держави, а продукту чи клієнта чи будь-чого іншого.

Але GetFooData (true) або GetFooData (42) ... це може означати що завгодно. Названі параметри - чудовий спосіб зробити самодокументацію. Я використовував їх саме для цієї мети неодноразово.

Немає ніяких надто зрозумілих причин, чому в першу чергу використовувати цей тип синтаксису.

Взагалі намагайтеся уникати булевих аргументів, які на відстані можуть виглядати довільно. includeManagementбуде (швидше за все) сильно впливати на результат. Але аргумент виглядає так, що він несе "невелику вагу".

Про використання перерахунку обговорювалося не тільки те, що це буде виглядати як аргумент "несе більше ваги", але й надасть масштабованість методу. Однак це може бути не найкращим рішенням у всіх випадках, оскільки ваш ReturnEmployeeIds-метод повинен масштабуватись поряд з WhatToInclude-енумом (див. NiklasJ ). Це може призвести до головного болю пізніше.

Врахуйте це: Якщо ви масштабуєте WhatToInclude-enum, але не ReturnEmployeeIds-метод. Потім це може викинути ArgumentOutOfRangeException(найкращий випадок) або повернути щось абсолютно небажане ( nullабо порожнє List<Guid>). Що в деяких випадках може заплутати програміста, особливо якщо вашReturnEmployeeIds перебуваєте в бібліотеці класів, де вихідний код недоступний.

Можна припустити, що WhatToInclude.Traineesспрацює, якщоWhatToInclude.All і є, бачачи, що слухачі є "підмножиною" всіх.

Це (звичайно), залежить від того, як ReturnEmployeeIds реалізовано.

У випадках, коли може бути передано булевий аргумент, я намагаюся замість цього розбити його на два способи (або більше, якщо потрібно) у вашому випадку; можна витягти ReturnAllEmployeeIds, ReturnManagementIdsі ReturnRegularEmployeeIds. Це охоплює всі основи і абсолютно не пояснює того, хто його виконує. Це також не матиме "масштабування" -тискання, згадане вище.

Оскільки існує лише два результати для чогось бугельного аргументу. Реалізація двох методів вимагає зовсім небагато додаткових зусиль.

Менше коду, рідше краще.

Зважаючи на це, є деякі випадки, коли явне оголошення аргументу покращує читабельність. Розглянемо, наприклад. GetLatestNews(max: 10). GetLatestNews(10)як і раніше досить зрозумілий, явна декларація maxдопоможе очистити будь-яку плутанину.

І якщо ви абсолютно повинні мати булевий аргумент, про використання якого не можна зробити висновок просто читанням trueабо false. Тоді я б сказав, що:

var ids = ReturnEmployeeIds(includeManagement: true);

.. абсолютно краще і читабельніше, ніж:

var ids = ReturnEmployeeIds(true);

Оскільки у другому прикладі це trueможе означати абсолютно все . Але я б спробував уникнути цього аргументу.