Чи правильно розміщувати посилання на сайти з питань запитання у коментарях програми?

У досить деякій кодовій базі ви можете побачити коментарі, в яких зазначається:

 // Workaround for defect 'xxx', (See bug 1434594 on Sun's bugparade)

Тож у мене є кілька питань, але всі вони пов'язані.

Чи правильно розміщувати посилання на питання SO в коментарях до програми:

 // We're now mapping from the "sorted-on column" to original indices.
 //
 // There's apparently no easy way to do this in Java, so we're
 // re-inventing a wheel.
 //
 // (see why here, in SO question: http://stackoverflow.com/questions/951848)

Ви робите це?

І які недоліки при цьому? (див. мій перший коментар про жахливий недолік)

Я це зробив, можливо, не спеціально для переповнення стека, але для технічних блогів, форумів, Usenet, груп Google або будь-яких інших місць, де "чому я це зробив" може бути не зовсім зрозумілим з контексту.

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

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

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

В ідеалі ваш код не потребує таких коментарів, тому що він добре структурований і т. Д. Але так, коли ваша ситуація менше ідеальної, прийнятно розміщувати такі коментарі. І посилання на stackoverflow.com настільки ж хороші (і часто кращі!), Ніж інші.

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

Я ще не поклав посилання StackOverflow.com у свій код. Я намагаюся уникати введення посилань у код, оскільки це поганий запах, але коли настане час, я не вагаюся.

Редагувати : Я думаю, що моя вище відповідь створює враження, що необхідність у коментарях, таких як ця, уникнути. Звичайно, іноді цього не уникнути; це помилка в бібліотеці або поганий дизайн API, над яким ви не маєте контролю. Такі коментарі, включаючи посилання, дуже корисні для наступного розробника.

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

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

Ви все одно повинні надавати кредит іншим, коли ви використовуєте їх ідеї.

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

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