Читать книгу Полезные конспекты книг и авторские заметки по информационным технологиям. Без формул онлайн

Комментирий не приводит к поиску расшифровки в других модулях.

Использовать аналог Javadoc.

Не комментировать бормотанием.

Не комментировать избыточно.

Комментарии точнее кода.

Комментарии точные и соответствуют коду.

Комментарий не вводит в заблуждение и не дезинформирует.

Бессмысленные или обязательные комментарии исключены.

Комментарий не повышает риск обмана и недоразумений.

Длинные журналы комментариев исключены.

Комментарии не загромождают и не усложняют код.

Комментарии-шумы исключены.

Комментарии не утверждают очевидное, не предоставляя новой информации.

Комментарии не бесполезны.

Комментарии не вызывают желания игнорировать их.

Комментарии не содержат эмоций.

Комментарии делают работу приятной и эффективной.

Комментарии не используются там, где можно использовать функцию или переменную.

Заголовки в комментариях применяются, когда приносят ощутимую пользу.

Закрывающие скобки не комментируются.

Ссылки на авторов в комментариях заменяются использованием системы контроля версий.

Нет закомментированного кода.

Нет HTML-комментариев.

Комментарии описывают код, к которому отнесены.

Комментарии не содержат дискуссий, исторических подробностей, не относящихся к делу.

Связь между комментарием и его кодом очевидна.

Цель комментария – объяснить код, который не объясняет сам себя.

Комментарий не нуждается в объяснении.

Комментарии для API общего пользования не помещаются в коде, не предназначенном для общего потребления.

Комментарий упрощает понимание алгоритма пользователем.

Код должен быть хорошо отформатирован.

Форматирование облегчает передачу информации.

Маленькие файлы понятнее больших.

Типичная длина файла 200 строк, предел – 500.

Исходный файл выглядит как статья.

Имя файла простое, но содержательное.

Имени файла достаточно, чтобы определить. этот модуль нужен или нет.

Начальные блоки файла описывают высокоуровневые концепции и алгоритмы.

Степень детализации увеличивается к концу файла.

В конце файла собираются все функции и подробности низшего уровня.

Код читается слева направо и сверху вниз.