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

В некоторой кодовой базе вы можете видеть комментарии, в которых говорится:

 // 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 - это стиль вики, поэтому возможно, что он может измениться, но в целом идея должна быть такой же.

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

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

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