День девятьсот шестой. #BestPractices
Лучшие Практики Написания Комментариев к Коду. Продолжение
Начало
Продолжение

6. Предоставляйте ссылки на источник скопированного кода
Если вы такой же, как и большинство программистов, вы «иногда» используете код, который находите в Интернете. Добавление ссылки на источник позволяет будущим читателям получить полный контекст, например:
- какая проблема решалась,
- кто предоставил код,
- почему рекомендовано это решение,
- что об этом думают комментаторы,
- работает ли это решение до сих пор,
- как его можно улучшить.

Например, рассмотрим этот комментарий:

/* Преобразует Drawable в Bitmap. 
См. https://stackoverflow.com/a/46018816/2219998 */

Переход по ссылке на ответ показывает:
- Автор кода - Tomáš Procházka, который входит в топ 3% контрибьюторов на Stack Overflow.
- Один комментатор предлагает оптимизацию, уже включенную в репозиторий.
- Другой комментатор предлагает способ избежать крайнего случая.

Сравните это с этим комментарием (слегка изменённым для защиты авторов):

// Магическая формула, взятая со stackoverflow.
// По общему мнению, основана на человеческом восприятии. 
return (int) (0.3 * red + 0.59 * green + 0.11 * blue);

Любому, кто захочет понять этот код, придётся искать формулу. Вставить URL-адрес намного быстрее, чем искать ссылку позже.

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

Люди копируют много кода из вопросов и ответов на Stack Overflow. Этот код подпадает под действие лицензий Creative Commons, требующей указания авторства. Комментарий со ссылкой удовлетворяет этому требованию.

Точно так же вы можете ссылаться на полезные учебные пособия, чтобы их можно было найти снова, а также в виде благодарности их автору:

// Большое спасибо Chris Veness за отличные примеры:
// http://www.movable-type.co.uk/scripts/latlong.html

7. Добавляйте ссылки на внешние источники, где они будут наиболее полезны
Например:

/* На http://tools.ietf.org/html/rfc4180 
 советуют завершать строки в CSV файле символом CRLF
 поэтому используем \r\n */
csvStringBuilder.append("\r\n");

Ссылки на стандарты и другую документацию могут помочь читателям понять проблему, которую решает ваш код. Хотя эта информация может быть где-то в проектном документе, комментарий в правильном месте даст читателям информацию там, где она больше всего нужна. В этом случае переход по ссылке даст полезную информацию о том, что стандарт RFC 4180 был обновлен до RFC 7111.

Окончание следует…

Источник: https://stackoverflow.blog/2021/07/05/best-practices-for-writing-code-comments/