Незначительные недостатки, кричащие о «коде для начинающих»

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

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

Давайте быстро рассмотрим эти недостатки, чтобы вы могли избежать их в своем коде!

Нет новой строки в конце файла

Существует соглашение UNIX о добавлении символов новой строки в конец каждого файла. Это началось из-за того, что инструменты командной строки, такие как cat, отображали множество файлов без каких-либо разделителей между ними. Git идентифицирует файлы по хешу их содержимого — даже разница в один символ делает файл другим для Git. Сочетание этих двух вещей приводит к тому, что Git и GitHub указывают на это каждый раз, когда в конце файла отсутствует новая строка.

Командная строка Git:

GitHub:

Многие проекты, которые я видел, требуют, чтобы каждый текстовый файл содержал символ новой строки — в соответствии с соглашением UNIX.

Решение

В вашем редакторе кода должна быть возможность добавить эти новые символы строки. Кроме того, вы можете проверить поддержку EditorConfig в вашем редакторе и настроить его на уровне проекта.

Несовместимый стиль кода

Пожалуйста, взгляните на этот код:

if (a == 1){
  b = 2;
} 
else {
  b =3;
}

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

Решение

Вам не нужно:

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

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

Зафиксировать сообщения

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

• В некоторых проектах журналы изменений создаются автоматически на основе коммитов. Например, angular использует conventional-changelog.
• История Git должна давать краткий обзор того, что произошло в проекте — беспорядочные сообщения усложняют переваривание.
• git fault указывает на фиксацию, изменившую заданную строку в последний раз — хорошее сообщение фиксации ускоряет понимание того, что и почему тогда произошло.

Для новичка, работающего над личным проектом, я бы придерживался следующего:

• использование глагола в повелительном наклонении от первого лица в настоящем времени: добавить index.html вместо добавить index.html или добавить index.html.
• сохранение последовательного использования заглавных букв — всегда начиная со строчной или прописной буквы.
• не использовать точку в конце сообщения.
• оставаться меньше 50 символов в сообщении фиксации. Немного больше — это нормально, но старайтесь не превышать 70. Большинство инструментов Git не упаковывают сообщения, поэтому длинные сообщения будут обрезаны или выведены за пределы экрана.

!важно CSS

Когда вы используете !important в своих стилях, вы ставите данное правило CSS выше любого другого. Это запах кода или способ достижения цели, когда дела в проекте уже пошли плохо. Когда вы используете !important, вы удаляете простую опцию переопределения значений более конкретными селекторами — ключевую функцию CSS. Единственная ситуация, когда вы не можете избежать !important, — это когда вы переопределяете другое правило, которое уже использует его и исходит из кода, которым вы не можете управлять, например из сторонних библиотек.

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

.side-bar.side-bar {
  color: green;
}

.content {
  color: blue;
}

сделает <div class="content side-bar">test</div> зеленым.

Структура папок и имена файлов

Мои ожидания относительно структуры кодовой базы таковы:

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

Примеры, которые не соответствуют этим ожиданиям:

• контроллеры/ некоторые-controller.ts другойконтроллер.ts

Вышеприведенное смешивает kebab-case с camelCase в именах файлов: неясно, как следует называть новые файлы.

админ/ какой-то class.ts классы/ другой класс.ts Просмотры/ index.html

В приведенном выше фрагменте смешаны папки, соответствующие вариантам использования (admin/), и папки, соответствующие типу файла (classes/). Неясно, к чему относится класс, связанный с администратором. * <код>очень/ вложенный/ папка/ файл.ts

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

Обзор

Эти несколько вещей кажутся незначительными для тех, кто только начинает программировать, но опытные программисты обычно обращают на них внимание и замечают. Разобраться с этим как можно раньше — это хорошая идея: так ваш код будет выглядеть более профессионально, а это поможет рецензентам сосредоточиться на более важных вещах.