Глава 13. Оформление кода
-
постарайтесь не вносить без обсуждения разнобой стилей,
если есть предметные пожелания по коррекции текущего — пишите в devel-distro@ или мне (mike@), обсудим;
-
перед тем, как делать существенные переработки уже имеющегося
кода — опять же опишите проблему, идею и предполагаемый результат,
порой могут выясниться непредвиденные последствия;
-
документируйте на русском (README) или английском (README.en) языке
то, что написали или изменили, если бы сами хотели прочесть описание
сделанного на месте другого человека; в любом случае старайтесь
внятно описывать коммиты, при необходимости также спрашивайте
совета: документация кода порой не менее важна, чем сам код,
и призвана не повторять его, но пояснять намерения и неочевидности.
рекомендации
-
трезво относитесь ко входным данным и не пренебрегайте кавычками:
название дистрибутива с пробелом или получение текста ошибки вместо
ожидаемого вывода команды могут привести к сложнодиагностируемым
ошибкам; вместе с тем в ряде случаев, где требуется пословная
обработка значений переменных или раскрытие шаблонов shell (*?[])
— кавычки могут оказаться лишними;
-
пользуйтесь if [ … ]; then …; fi вместо [ … ] && …:
это кажется более громоздким, но текст оказывается более читаемым
и в т.ч. расширяемым, поскольку между then/else/fi можно спокойно
добавлять строки; с && проще забыть { … } или оставить ненулевой
код возврата при неудаче теста, когда он считается несущественным;
-
предпочтительно применение $() вместо `` (особенно при вложенности);
-
постарайтесь не вылезать за 80 колонок;
-
избегайте merge-коммитов в коде, который предлагаете для включения
в основную ветку, предлагайте pull-реквесты без конфликтов при мерже,
что облегчит работу с промежуточными состояниями.
ссылки
