Расскажу, почему я так дорожу комментами и документацией. Когда

я начал работать с приборами и протоколами связи, то мне открылся океан геморроя. Сотни моделей и версий приборов. Тысячи исходников, сотни тысяч классов, процедур и функций. Около ноля документации, все как по учебнику.

Постоянно возникал вопрос - как оно ДОЛЖНО работать? Как оно сейчас работает понятно - херово работает, с ошибками. В одном месте исправляешь - в другом отваливается. Потому что исправлялась ошибка, а не ее причина. А когда пытался найти и исправить причину - мне хором орали "не лезь, не трогай, все сломаешь, никто не починит". Но я потихоньку собирал информацию и записывал ее сначала в вордовские файлы, потом в вики.

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

Дальше надо было проверить эту документацию, написать минимально рабочий код. Часть кода взято из готового (алгоритмы CRC, шифрования, байтстаффинга), остальное написано с нуля по документации. Получилось что-то вроде простенькой демки, где виден каждый шаг, каждое действие. И тут паззл начинает складываться.

Например, у одного прибора был нюанс - нельзя чтобы в CRC получалась определенная комбинация байтов, которая означала маркер заголовка. И поэтому для него извратили функцию расчета CRC, чтобы в таком случае она "патчила" данные и считала новый CRC. Ведь это же совершенно очевидно по названию GetCrcEx! Ту же функцию применяли и для других версий приборов, где нюанса не было.

Ну или в заголовке есть поле с диапазоном значений 1..99. А в коде нигде это не упоминается. И нет соглашения о названиях, чтобы отличать 0-based "Index" от 1-based "Number". От этого код был забагован вдоль и поперек в принципе.

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

Там еще много чисто программных багов было поправлено благодаря комментированию и приведению кода к стандарту style guide, долго рассказывать. Ну, к примеру для события OnIncomingData был написан большой комментарий, что это событие блокирует чтение данных и поэтому в его обработчике нельзя ни гуй трогать, ни ввод-вывод и лучше сразу из него выходить.

еще не прочитал, но уже понял что код у тебя хорошо закоментирован))

у нас тоде множество подобных проблем. решаем просто: код - отдельно, комменты - отдельно в баг трекере. подход, в общем оправдался