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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Законченные мысли отделяются пустыми строками.

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

Тесно связанные концепции не находятся в разных файлах.

Следует избегать запущенных переменных.

Читателю не нужно прыгать туда-сюда по исходным файлам и классам.

Переменные объявляются максимально близко к месту использования.

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

Управляющие переменные циклов объявляются внутри конструкции циrла.

Переменные экземпляров объявляются в начале класса.

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

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

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

Важные концепции излагаются сначала с минимальным количеством второстепенных деталей.

Строки делать по возможности короткими.

Пробелы для визуального обозначения приоритета операторов.

Длинные списки – причина для разделения на классы.

Горизонтальное выравнивание не применяется.

Отступы выделяют области видимости.

Не применяются вырожденные области видимости.

Группа разработчиков согласует единый стиль форматирования.

Код продукта оформлен в едином стиле.

Внешний пользователь не в курсе деталей реализации.

Методы интерфейса устанавливают политику доступа к данным.

Классами предоставлены абстрактные интерфейсы, посредством которых пользователь оперирует с сущностью данных.

Пользователь не имеет представления о фактическом формате данных.

Объекты скрывают свои данные за абстракциями и предоставвляют функции, работающие с этими данными.

Структуры данных раскрывают свои данные и не имеют осмысленных функций.