Я ненавижу большинство стандартных документов, потому что они обычно пытаются потеть мелочи и игнорируют общую картину.
Например, почти все из них скажут, как называть переменные или ставить скобки. Это чистый стиль, и он мало помогает правильному кодированию группы разработчиков. Они игнорируют такие вещи, как структура каталогов и макет кода. Я видел стандартные документы, в которых точно указывалось, сколько пробелов ставить между операторами и сколько пустых строк ставить между методами. Все это обычно заканчивается множеством исключений из правила, которое просто показывает, насколько они бессмысленны, а затем они настолько велики, что никто не может им следовать, что опять же высмеивает то, что они пытаются сделать ,
Теперь я использую много разных программных продуктов от разных людей, и у них у всех разные стили. Я просто привыкаю к этому, я не жалуюсь, что не существует общего стиля для всех групп разработки. Пока код является общим стилем для всего проекта, мне действительно все равно, что это за стиль. Поэтому мое первое правило для всех стандартных документов: придерживайтесь единого стиля кодирования в проекте . никто не должен показывать, где скобки, если они все одинаковые. Возьми религиозные войны и запихни их :)
Второе - это макет кода. Когда я беру кусок кода, я хочу видеть, что он выложен по тем же принципам, что и другие, похожие работы. Если у меня есть веб-сервис, я хочу, чтобы имя контракта wsdl было понятным, я хочу, чтобы имя реализации было понятным. Я не хочу, чтобы кто-то придумал совершенно новый и другой макет для файлов и классов. Это означает, что я должен играть в «охоту на код», что является неприятностью. Если он выглядит так же, как и последний проект, над которым я работал, я сразу же могу узнать, где найти то, что я ищу, и это, вероятно, самая большая помощь в работе с чужим кодом, который я знаю. Таким образом, сохраните структуру того, как выложен код (например, папка «Документация» для документов, интерфейсы для интерфейсов и т. Д. - что бы это ни было для вас, но придерживайтесь его).
Также должны присутствовать артефакты кода, поэтому вы должны сказать, является ли ожидаемая обработка ошибок исключениями или кодами ошибок - т.е. Архитектурная функциональность документа, которая используется . В нем также должно быть указано, какой тип ведения журнала использовать и как представить журналы / обработку ошибок пользователю или какую-либо подсистему, используемую для управления кодом на свободе. Я работал в месте, где каждый проект вел свою регистрацию по-разному - было жалко, что в каждом выпуске кода должен был быть свой собственный документ с описанием операций, рассказывающий парням-операционистам, как сказать, что все пошло не так. Журнал событий, файл журнала (в этом случае где), и т. Д. Все действительны здесь. То же самое относится и к другим общим аспектам кода - как его настроить (нет смысла использовать файл .config для некоторых программ, или пользовательскую БД, или параметры командной строки, или реестр для других).
Короче говоря, единственное, что имеет значение, это последовательность . А поскольку огромные документы по стандартам слишком сложны для чтения и запоминания, я предпочитаю просто информировать людей о вещах, которые они не могут видеть (например, об архитектурных стандартах, таких как ведение журнала), и просить их поддерживать код, который они пишут, в соответствии с тем, что есть в настоящее время. А если у вас уже нет кода, тогда вам не нужен документ по стандартам! (ну, пока вы не написали достаточно, чтобы сделать его полезным).
Итак, возьмите из этого основные моменты: не пытайтесь сделать юридический документ , думайте о вещах, которые не только кодируют, но также и как код работает и как код соответствует ожиданиям других людей. Тогда доверьтесь людям делать хороший код, и вы увидите, что они делают. (и если они этого не делают, вы не можете говорить с ними, нет необходимости устанавливать это как закон).