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

16

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

 // 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)

Ты делаешь это?

И каковы недостатки в этом? (см. мой первый комментарий для ужасного недостатка)

Ул. Тристан
источник
9
комментируя себя: один очень существенный недостаток при этом заключается в том, что из-за того, что SO - это Wiki, нет абсолютно никакой гарантии, что ответ (ы), на которые вы полагаетесь, все равно будут правильными (или даже будут присутствовать). Черт, в некоторых случаях сам вопрос может быть закрыт или изменен с его первоначального значения. Огромная разница между «See ошибкой 1434594» на ошибке параде Sun является то , что вы гарантированы , что текст от ошибок линии Солнца не должен ( «не должны» изменения , как в определяется RFC2119). Это огромно: тот факт, что SO - это вики, заставляет меня нервничать, помещая SO ссылки в комментарии.
ул. Тристан
7
Лучше всего сделать ясную и краткую сводку ответа SO, а затем поместить ссылку под ним. Я делал это несколько раз. Таким образом, если SO когда-либо потерпит неудачу или ответ будет удален / отредактирован, основная информация, которую вы хотели, все еще находится в вашем резюме. Теперь, в зависимости от сложности ответа, написание резюме может быть целой отдельной работой. Если SO-ответ ссылается на что-то еще, возможно, стоит того, чтобы на него ссылались (особенно если они менее эфемерны, чем SO-ответы).
FrustratedWithFormsDesigner
5
@ Роберт С .: нет, это не мета. Это не так: я принимаю так, как есть. Это конкретно о том, как обращаться с SO-подобным ресурсом из комментария.
ул. Тристан
1
Вы говорите о коде, который вы пишете для своей команды? Спроси их.
1
Вы всегда можете сохранить всю веб-страницу как полную веб-страницу, сжать ее и поместить в папку с документами.

Ответы:

7

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

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

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

Джо Энос
источник
5

Как правило, лучший способ создать эту ссылку - через систему контроля версий и / или систему отслеживания ошибок. Требование для того, чтобы это работало, это то, что вы можете точно связать свой код с системой отслеживания ошибок или местом в системе управления версиями, где вы размещаете свои комментарии.


источник
это интересно: так вы на самом деле предлагаете, чтобы в случае SO-ответа я мог получить HTML-код и сохранить его в моем DVCS (Mercurial, но это не главное)?
ул. Тристан
Ну, обычно вам не нужно все это, только соответствующие биты, верно? И вы можете сослаться на источник.
5

В идеале ваш код не нуждается в таких комментариях, потому что он хорошо структурирован и т. Д. Но да, когда ваша ситуация не идеальна, это приемлемо в такие комментарии добавлять такие комментарии. И ссылки на stackoverflow.com так же хороши (и часто лучше!), Чем другие.

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

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

Изменить : я думаю, мой ответ выше создает впечатление, что необходимость в комментариях, таких как это можно избежать. Конечно, иногда этого не избежать; это ошибка в библиотеке или плохой дизайн API, который вы не можете контролировать. Подобные комментарии, включая ссылки, очень полезны для следующего разработчика.

Патрик Керхер
источник
2
эй, посмотрите на это, я бы хотел , чтобы был более «чистый» способ справиться с этим, но очень часто это не тот случай, когда stackoverflow.com/questions/951848 Я имею в виду ошибки и несоответствия / странный API, недокументированное поведение и т. д. являются частью нашей жизни программиста :)
Tristan St.
2

Я рассматриваю это как написание исследовательской работы. Если я использую чужие идеи, мне нужно отдать должное этим идеям. Я использовал ответ от stackoverflow в своем коде ранее, и я добавил ссылку на комментарии метода.

Как кто-то упоминал, SO - это стиль вики, поэтому возможно, что он может измениться, но в целом идея должна быть такой же.

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

jmq
источник
1

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

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

S.Robins
источник