Coding

Как сделать, чтобы код не стал Legacy

1. Чётко обозначить решаемую задачу

2. Решить её на 100%, выполнить все возникшие при разработке TODO

3. Обеспечить интерфейс документацией, описать интерфейс (например командной строки), привести примеры использования, ВСЕ, имевшиеся в виду при разработке.

4. Не допускать подхода GIGO, проверять все значения - лучше чуть медленнее, чем сумничать, а потом будут сношать во все щели.

5. Концептуальная документация - описание разработки сверху вниз. Описание сверху вниз: какие компоненты в программе, как она разделена на модули. Какие модули какую функцию выполняют, почему разделение сделано именно так.

6. Документация данных: как данные хранятся, какие типы используются. Какие значения возможны, в каких случаях используются те или иные типы и структуры.

7. Описание динамики. Процессы загрузки, старта, работы, завершение. Процесс работы, создание, удаление сессий. Всё так же, от общего к частному.

8. Не надо комментариев a=a+1 "увеличиваем a на единицу" - не надо считать других разработчиков дебилами. Комментарий должен объяснять, ЗАЧЕМ a тут увеличивается на 1.

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

10. Не писать одно и то же два раза - ибо это муторно. Если функцию надо иметь в двух вариантах, должен быть один параметризованный. Возможно, использовать какой-то флаг. Если выполняются разные действия - параметризована функция, которая вызывается (объект или функция+контекст).

Пример муторности "два раза" - getopt. Один раз перечисляем параметры командной строки, второй раз их перечисляем, когда описываем действия при обнаружении параметров. А реально достаточно одного раза - указать параметр и функцию, библиотека из этой информации вполне может составить список допустимых параметров - очевидно, что список допустимых параметров тот же, что и список параметров, который обрабатывается. Ведь если параметр, на который определена функция, посчитать недопустимым, функция никогда не вызовется. Если нужен параметр, на который нет никакой реакции - достаточно определить пустую функцию.