Чистый код №2

Они применяются для именования всего: переменных, имен классов, методов, пакетов и т. д.

Когда у вас есть семантическая модель свежая в голове, это легко чтобы сопоставить ваш код с его

Нетрудно запомнить, что переменная с именем x – это дата записи. strong> был создан, а г – дата его удаления.

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

Источник: Почему ваш код так сложно понять

Комментарии

Комментарии могут лгать. В коде нет.

В идеале ваш код должен быть настолько хорош, чтобы не требовать комментариев.

Это может быть не так в одном случае, когда вы кодируете что-то странное и требуете объяснения для предметной области.

Как и в машинном обучении, выбор определенных параметров или определенного шага можно лучше понять, поместив ссылку на пояснение/исследование в комментарии. Читая только код, читатель может не понять, что с ним делать. (Источник: Джереми Ховард fast.ai).

Намерение давать имена

Используйте произносимые имена

Переменные должны быть названы так, чтобы было ясно, что они содержат.

Имена переменных всегда должны быть легко читаемыми, быть короткими, но осмысленными, в смешанном регистре со строчной первой буквой английского слова.

b)Используйте множественное число имен для массивов/наборов объектов.

c) Постоянные (статические final) имена переменных должны быть всеми заглавными буквами и отдельными словами в имени с знак подчеркивания, т. е. PRIORITY_NORMAL,

Источник: Соглашение о кодировании Java и чистый код

Для матричных операций используйте столбцы строк вместо y и x, потому что в некоторых языках матрица обрабатывается как [y,x]

Источник: Гейл Лаакманн Макдауэлл (взлом книги интервью по программированию)

Аббревиатуры и краткие формы

Многие люди пытаются оптимизировать вертикальное пространство экрана, но забывают о горизонтальном пространстве.

Это своего рода исключение из приведенного выше правила: для очень и очень распространенных вещей лучше использовать краткие формы. (Вы также печатаете меньше).

Только не сокращайте все до одной буквы. Будьте небольшими, но описательными.

Кроме того, может быть полезно иметь список сокращений, используемых в файле readme/документации вашего проекта.

Примеры,

  1. repo для репозитория
  2. util для полезности.
  3. serv для обслуживания
  4. len для длины
  5. dto для объекта передачи данных (довольно часто)

Убедитесь, что везде в коде используются одни и те же сокращения, т. е. одно слово на понятие во всех классах.

(Ниже приведены примеры для имен методов)

  • получить / получить / найти
  • установить/обновить

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

Магические числа и строки

Любое число или строка в вашем коде, не сразу очевидная для человека с очень небольшими знаниями.

Источник: Стакововерфлоу

Лучше объявить их в отдельном файле констант.

Константы должны быть змеей_case и CAPITAL.

В случае с Java перечисления также можно использовать для достижения чего-то подобного, но они будут содержать много шаблонного кода Java.

Существуют также соглашения об именах для конкретных языков, такие как:

  1. Java и Typescript предпочитают camelCase
  2. Python и SQL предпочитают змеиный регистр

Для модульных тестов

Моя цель не столько в сокращении количества строк кода. Тесты обычно небольшие. (В случае, если ваши тесты огромны и сложны, вы, должно быть, написали плохой код)

Я предпочитаю, чтобы конец каждого метода был одинаковым. Нравится:

Я использую Mockito, поэтому пропускаю первую строку. Тогда запуск функции происходит со всеми действиями-заглушками.

Последние 3 строки обычно похожи.

  1. Переменная ожидаемое: ожидаемое значение
  2. Переменная actual: вызывает функцию/метод
  3. утверждение

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

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

Предыдущая: Плоский лучше, чем вложенный

Далее: Избегайте создания богоподобных классов и длинных методов #NotEnoughChunks

Предметный указатель: Советы по написанию чистого кода