кто знает где можно найти даташит на этот "прекрасный" АЦП?
К512ПВ1

Что-то мне подсказывает что это 572я серия всё-таки

code style guide в сорцы не закинешь,; в больших проектах без краткой обзорной доки сложно ориентироваться; без комментов, хотя бы, вида "эта функция делает то-то", "этот блок делает то-то"  придётся всё последовательно вычитывать пока найдешь нужное место.
А ещё критерии "самодокументированности" разные. Комменты это считается за документацию?
В целом я ни одного крупного проекта, даже опенсорсного, без тех же обширных комментов не встречал. Вернее встречал парочку, но у них мейнтейнеры в каком-нибудь специальном чате с кучей участников сидят и постоянно поясняют чо-как-куда. А утверждения про самодокументированность и ненужность комментов в основном слышатся от людей, которые ковыряют один-два своих проекта и, естественно, знают всё вдоль и поперёк. У них experience bias фактически.

очень интересно, спасибо.
Дело тут вот в чем. Один мой друг с довольно обширным опытом, будучи тим лидом SW писал на питоне scheduler на спутник вообще без комментариев, утверждая, что это гуд практис и вообще самодокументированный код. Может где-то была дока с описанием, но когда мне пришлось разбираться с движком телеметрии, я рыл сырой код as is и это была боль.
Сомнений в его компетенции у меня не было и нет, но вот тот момент в память запал, потому что показался реально странным.

Имхо обилие нормальных комментариев никогда и никому не помешает. Если ты такой Есус, то просто не смотри в них, смотри код, благо ide современные позволяют "погасить" комменты, например, задав им бледно серый цвет в цветовой схеме.

Без комментариев даже в своих проектах, которым 3-4 года разобраться сложно. В последние года 1,5 перешел на связку "комменты+микро коммиты+подробная структурная схема графическая" и это позволило не только самому сильно проще дорабатывать код и еще другие люди без проблем могут разобраться что в нем происходит.

P.S. не синьор и даже не помидор и проекты не сильно большие

О благодарю
наконец нашел

Уже  только одно "шедулер на спутник на питоне"питоне" заставляет задуматься.
Если этот код будет ковырять только он, ну, максимум, кто-то, кому дадут много времени чтобы разобраться в коде - допустимо. Но в общем и целом когда я пишу код вообще без комментов не для себя лично, я знаю что поступаю как, простите, мудак. И не втираю про бест пруктисес.

Есть несколько простых правил
именуете функции по смыслу
переменные - тоже самое
уже половина кода понятна будет

public с больших букв, локальные с маленьких

глобальные переменные можно запихать в структуры и тогда понятнее откуда они берутся

это код стайл, он улучшит читаемость кода, но не позволит разобраться в большом проекте сходу

а писать комантрии (из реального кода)
++idx; // увеличиваем индекс массива
на хер не нужны

Так такое студенты пишут или студенты, которые претворяются программистами)

а я для большого есть другие инструменты - Source Insight

в Visual Studio есть что бы в графическом, но это что бы логику понять и взаимосвязи.

Такие не нужны. Комменты нужны для облегчения навигации по коду и для краткой анннотации для блоков со всратой математикой.

при желании всегда разобратся можно.

А, да. Особенно для блоков с математикой, в которой магические константы есть

с математикой сложнее - её надо знать 😊

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