Чи вважається поганою практикою включення номера помилки до назви методу для тимчасового вирішення?

Мій колега, який є старшим хлопцем, блокує мене в огляді коду, тому що він хоче, щоб я назвав метод "PerformSqlClient216147Workaround", тому що це спосіб вирішення деяких дефектів ###. Тепер моя пропозиція щодо імені методу - це щось на кшталт PerformRightExpressionCast, яке має тенденцію описати, що саме метод робить. Його аргументи йдуть по лінії: "Добре, що цей метод використовується лише як спосіб вирішення цього випадку, і більше ніде".

Чи вважатиметься включенням номера помилки всередині назви методу для тимчасового вирішення поганою практикою?

Я б не назвав метод, як запропонував ваш колега. Назва методу повинна вказувати, що робить метод. Ім'я на зразок PerformSqlClient216147Workaroundне означає, що він робить. Якщо будь-що, використовуйте коментарі, що описують метод, щоб згадати, що це спосіб вирішення. Це може виглядати наступним чином:

/**
 * Cast given right-hand SQL expression.
 *
 * Note: This is a workaround for an SQL client defect (#216147).
 */
public void CastRightExpression(SqlExpression rightExpression)
{
    ...
}

Я погоджуюся з MainMa, що номери помилок / дефектів не повинні відображатися у самому вихідному коді, а у коментарях до джерела, оскільки це метадані, але це не страшно, якщо вони з'являються у коментарях до вихідного коду. Номери помилок / дефектів ніколи не повинні використовуватися в назвах методів.

Ніщо не є більш постійним, ніж тимчасове виправлення, яке працює.

Чи добре виглядає його пропозиція через 10 років? Раніше було звичайною практикою коментувати кожну зміну з виправленим дефектом. З недавніх пір (як і останні 3 десятиліття), цей коментар стилю широко прийнятий як зменшення ремонту коду - і це просто коментарями, а не назвами методів.

Те, що він пропонує, є переконливим доказом того, що ваші системи контролю якості та якості суттєво недостатні. Відстеження дефектів та виправлень дефектів належить до системи відстеження дефектів, а не вихідного коду. Відстеження змін вихідного коду належить до системи управління джерелом. Перехресне посилання між цими системами дозволяє простежити дефекти вихідного коду .....

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

Так це тимчасове рішення? Потім використовуйте ім'я, запропоноване рецензентом, але позначте метод як застарілий, щоб його використання створювало попередження кожного разу, коли хтось збирає код.

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

Зауважте, що навіть у коментарях, кількість помилок сама по собі не дуже цінна. Уявіть такий коментар:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The following method replaces FindReportByDate, because of the bug 8247 in the
    // reporting system.
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

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

Висновок: ви поняття не маєте, про що йдеться про цю помилку.

Той самий код міг бути написаний дещо по-іншому:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The reporting system we actually use is buggy when it comes to searching for a report
    // when the DateTime contains not only a date, but also a time.
    // For example, if looking for reports from `new DateTime(2011, 6, 9)` (June 9th, 2011)
    // gives three reports, searching for reports from `new DateTime(2011, 6, 9, 8, 32, 0)`
    // (June 9th, 2011, 8:32 AM) would always return an empty set (instead of isolating the
    // date part, or at least be kind and throw an exception).
    // See also: http://example.com/support/reporting-software/bug/8247
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportsByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

Тепер ви отримаєте чітке уявлення про проблему. Навіть якщо здається, що гіпертекстова посилання в кінці коментаря п'ять років тому мертва, це не має значення, оскільки ви все ще можете зрозуміти, чому FindReportsByDateїї замінили FindReportsByDateOnly.

Я тоді знаходжу PerformSqlClient216147Workaroundбільш інформативним PerformRightExpressionCast. У назві функції взагалі не виникає сумнівів щодо того, що вона робить, чому це робить, або як отримати більше інформації про неї. Це явна функція, яку буде дуже просто шукати у вихідному коді.

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

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

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

Однак це також дозволяє припустити, що єдиною причиною існування функції є обхід помилки. Тоді, якби проблема не була проблемою, ви б не хотіли, щоб це робило програмне забезпечення. Імовірно ви робите хочете програмне забезпечення , щоб робити свою справу, так що ім'я функції має пояснити , що він робить і чому домни проблеми вимагає , щоб зробити; не для чого потрібна база даних про помилки. Рішення має виглядати як частина програми, а не як пов'язка.

Я думаю, що і ти, і він дістали цю річ непропорційно.

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

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

Так чи інакше, ви і він маєте кращі справи.

Чи вважатиметься включенням номера помилки всередині назви методу для тимчасового вирішення поганою практикою?

Так.

В ідеалі ваш клас повинен найкраще відображати / реалізовувати концепцію у потоці / стані програми. Назви API цього класу повинні відображати те, що вони роблять для стану класу, щоб клієнтський код міг легко використовувати цей клас (тобто не вказувати ім’я, яке буквально нічого не означає, якщо ви спеціально не читаєте про нього).

Якщо частина загальнодоступного API цього класу в основному говорить "виконувати операцію Y, описану в документі / розташуванні X", тоді здатність інших людей розуміти API залежатиме від:

1. вони знають, що шукати у зовнішній документації

2. вони знають, де шукати зовнішню документацію

3. вони забирають час і сили і насправді шукають.

Знову ж таки, назва вашого методу навіть не вказує, де "дефект X" для цього дефекту.

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

Принаймні, якщо ви знаєте, що дефект завжди буде доступний в одному місці, і це не зміниться (як-от номер дефекту Microsoft, який був за тією ж URL-адресою протягом останніх 15 років), ви повинні надати посилання на питання в документації API.

Незважаючи на це, можуть бути вирішені інші дефекти, які стосуються більше, ніж API одного класу. Що ти будеш робити тоді?

Маючи API з однаковим номером дефекту в декількох класах ( data = controller.get227726FormattedData(); view.set227726FormattedData(data);насправді не дуже багато, і просто робить код більш незрозумілим.

Ви можете вирішити, що всі інші дефекти вирішуються за допомогою імен, що описують операцію ( data = controller.getEscapedAndFormattedData(); view.setEscapedAndFormattedData(data);), за винятком вашого дефекту 216147 (який порушує принцип дизайну "найменшого надмірності" - або якщо ви хочете поставити так, це збільшує вимірювання "WTF / LOC" вашого коду).

TL; DR: Погана практика! Іди до своєї кімнати!

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

Названня методу обходу (.... Обхід). Здавалося б, досягти цієї мети. Сподіваємось, на деякому етапі основна проблема буде виправлена, а метод усунення вирішено.

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

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

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

Мій співробітник одного разу сказав: "Виправляючи дефект, зробіть код таким, яким він мав бути". Як я трактую це: "Змініть код так, як він виглядатиме, якби ця помилка ніколи не існувала".

Наслідки:

1. Зазвичай, менше коду в результаті.
2. Прямий код
3. Менше посилань на помилки у вихідному коді
4. Менший ризик подальшої регресії (коли зміна коду повністю перевірена)
5. Простіше аналізувати, оскільки розробникам не доводиться обтяжувати себе історією навчання, яка вже не є актуальною.

Вихідний код не повинен мені розповідати, як він дійшов до його поточного стану. Управління версіями може розповісти мені історію. Мені потрібен вихідний код, щоб просто знаходитися в стані, необхідному для роботи. Однак, випадковий коментар "// помилка 12345" не є поганою ідеєю, але його зловживають.

Тому, вирішуючи, чи називати ваш метод "PerformSqlClient216147Workaround", задайте собі наступні питання:

1. Якби я знав про помилку 216147 перед тим, як писати код, як би я це обробляв?
2. Що таке вирішення? Якби хтось, хто ніколи раніше не бачив цього коду, дивився б на нього, чи змогли б він його дотримуватися? Чи потрібна перевірка системи відстеження помилок, щоб знати, як працює цей код?
3. Наскільки тимчасовий цей код? На мій досвід, тимчасові рішення зазвичай стають постійними, як вказує @mattnz.