В каком формате вы пишете документацию к своим проектам?

Sphinx для пистона. В последнее время пытаюсь обязать чатгопоту это делать на MR, ну или хоть проверять что дока все ещё актуальна

Пальцем покажете? Мне вот, например, из прототипа hh_parse не очевидно, что сохраненные в r_name/r_value указатели подлежат освобождению вызывающей стороной.

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

Что до очевидного, то мне лично пришлось долго вкуривать что делает вот этот фрагмент:

Подстрочник перевода:

все подчёркивания и дефисы заменить на дефис
не первую или не после дефиса: большие заменить на маленькие
после дефиса или первую: маленькие заменить на большие
если встретилось что-то кроме дефиса, подчёркивания, буквы или цифры, вернуть -3

Это требует дополнительного комментария?

Лучше было бы сделать enum.

Да. enum был бы эквивалентен этому комментарию.

Но теперь встречный вопрос: вы реально считаете, что комментарий, в котором перечислены целочисленные значения, и эти же целочисленные значения захардкожены в теле функции – это норм?

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

Как раз чтобы не делать таких ошибок:

  if(n==MAX_HEADER_NAME) return HH_PARSE_BAD_NAME;

А что означает имя переменной ow так и осталось для меня загадкой.

Какое предлагаешь имя для состояния «не после дефиса и не первый символ»?

Так тип же указывает.

Он ничего не указывает. Из типа даже не видно, можно ли туда отдать NULL (скажем, если нас интересует только имя, но не интересует значение).

Это требует дополнительного комментария?

Комментария требует не перечень действий, а цель их выполнения. Например, если бы перед этим говноциклом был комментарий вида:

/*
  Имена вида «HEADER_name_WiTh_SeVeRaL-WORDs» требуется преобразовать
  к канонической форме «Header-Name-With-Several-Words»
*/

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

Да. enum был бы эквивалентен этому комментарию.

enum в чистом Си никаких гарантий не дает.

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

Поздравляю, ваше мнение на тему программирования стало стоить еще меньше. Вот не зря когда у человека увлечение Lisp-ом в анамнезе, это сказывается необратимым образом на адекватности.

Какое предлагаешь имя для состояния «не после дефиса и не первый символ»?

Мое дело не предлагать, а сходу понимать что в коде написано. Имя переменной ow этому не помогает от слова совсем.

По смыслу действий в обсуждаемом говноцикле имя word_started было бы гораздо лучше, чем ow.

enum в чистом Си никаких гарантий не дает.

комментарий тоже

Имена вида «HEADER_name_WiTh_SeVeRaL-WORDs» требуется преобразовать

Как из этого комментария угадать, во что преобразовывается «header_-213name»? Полное ТЗ на этот код занимает столько же строк, сколько сам код.

Из типа даже не видно, можно ли туда отдать NULL (скажем, если нас интересует только имя, но не интересует значение).

Это тоже особый случай, указываемый в комментарии.

Поздравляю, ваше мнение на тему программирования стало стоить еще меньше.

Да пожалуйста. Для меня ваше мнение немного стоит. Потому что когда правила определяют по «так принято», а не по реальным потребностям конкретного проекта, велика вероятность сделать плохо, применив ритуал там, где он не предназначен.

Например, когда пишут

double celsius_to_fahrenheit(double celcius)
{
  celcius * ONE_CELCIUS_IN_FAHRENHEIT + CELCIUS_0_IN_FAHRENHEIT;
}

Тоже, ведь, «чтобы не хардкодить константы». Или что-то совсем математическое типа расчёта потерь , где все числа заменены именованными константами.

По смыслу действий в обсуждаемом говноцикле имя word_started было бы гораздо лучше, чем ow.

Так тут как раз не started, а наоборот, любой символ кроме начального.

Имя переменной ow этому не помогает от слова совсем.

Значит оно предполагает некое сложное условие. Которое тривиально выводится из текста функции (сначала ложно, после дефиса ложно, после любого другого символа истинно).

Html

комментарий тоже

Поэтому коментария с перечислением целочисленных кодов быть не должно. А он есть. И его наличие множит на ноль категорические высказывание firkax-а о документировании кода.

Как из этого комментария угадать, во что преобразовывается «header_-213name»?

А это и не требуется. Для деталей нужно лезть в RFC для HTTP1.1. И показанный мной комментарий однозначно дает понять читателю кода что делается.

Было бы желательно еще и рассказать зачем это делается. Но это уже в большей степени придирки. И о том, что имена заголовков хранятся в преобразованном к каноническому виду лучше было бы записать в комментариях к структуре t_http_headers. Но таких описаний вы в коде firkax-а не найдете.

Это тоже особый случай, указываемый в комментарии.

Только вот в описаниях к функциям hh_add и hh_parse ничего подобного нет. Поэтому если в код заглядывает не firkax, а посторонний человек, ему нужно проштудировать код hh_parse, чтобы понять что можно в hh_parse отдавать, а что нет.

Потому что когда правила определяют по «так принято»

Правила определяют не потому, что «так принято», а потому что шишек уже было набито немерянно. Потому что кому-то еще на первом курсе профильного ВУЗа объяснили, что вот такой код:

int r = hh_parse(...);
if( -3 == r ) { ... }

рано или поздно «стрельнет», когда константа -3 перестанет использоваться и будет заменена на что-то другое. А вот у такого кода:

int r = hh_parse(...);
if( HH_PARSE_BAD_VALUE == r ) { ... }

шансов выжить при сопровождении больше. И, что характерно, потом ты видишь только подтверждения этого опыта, а не опровержения.

Например, когда пишут

Ничего плохого в этом не вижу. Более того, если этот код выйдет за пределы чистого Си, например, в современный C++ и пребразуется в шаблон, где типом будет не double, а T, то за именованными константами начнут скрываться template variable, но сам код такой функции не поменятся. Более того, за символом ONE_CELCIUS_IN_FAHRENHEIT может быть спрятан не просто (9/5), а какой-то специальный тип вроде std::ratio.

Так тут как раз не started, а наоборот, любой символ кроме начального.

Мне таки кажется, что как раз started. И цикл может быть переписан как-то так:

int word_started = 0;
for( n = 0; c = name[n]; ++n )
{
  if( '_' == c || '-' == c ) { name[n] = '-'; word_started = 0; }
  else f( c >= 'A' && c <= 'Z' )
  {
    // Если очередное слово начато, то прописные буквы
    // нужно заменять строчными.
    if( word_started ) name[n] = c - 'A' + 'a';
  }
  else if( c >= 'a' && c <= 'z' )
  {
    // Если очередное слово еще не начато, то первая строчная
    // буква должна быть заменена
    if( !word_started )
    {
      name[n] = c - 'a' + 'A';
      word_started = 1;
    }
  }
  else if( c >= '0' && c <= '9' ) { word_started = 1; }
  else
    return HH_PARSE_BAD_NAME;
}

Значит оно предполагает некое сложное условие.

Какое? Если оно что-то предполагает, то это должно быть описано.

Опишу то, что использую для своих собственных проектов.

Для книг и руководств использую latex (pdflatex). Для английского языка мне нравится шрифт palatino (\usepackage[T1]{fontenc};\usepackage{pxfonts}), для русского выбрал новый вебовский шрифт (\usepackage{paratype};\usepackage{microtype}).

Как сделали в латехе для английского - мне нравится. А вот то, как сделали для русского, - неплохо было бы еще verbatim доделать

Пару вещей написал на markdown через hakyll, но у меня все равно предпочтение в сторону PDF. Документ PDF - законченная и целостная вещь, что мне нравится. Это просто личные предпочтения

А так постоянно нахожусь в поиске чего-то лучшего, но пока не нашел идеала. Из всего, что видел, мне больше всего понравился FrameMaker, но его давно продали (во всех смыслах)

P.S. На своих работах использовал confluence и ms word. Не зашло

Поэтому коментария с перечислением целочисленных кодов быть не должно

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

Для деталей нужно лезть в RFC для HTTP1.1. И показанный мной комментарий однозначно дает понять читателю кода что делается.

Где в показанном вами комментарии указание RFC? Однозначно же он не даёт понять. Контрпример я привёл. С таким же успехом можно написать комментарий «целые числа преобразуются в целые, например 5 в 120».

Было бы желательно еще и рассказать зачем это делается.

??? Для использования в следующей строке процедуры, очевидно.

Использование процедуры hh_parse, её ограничения и допущения пишутся в документации, а не в тексте процедуры.

И о том, что имена заголовков хранятся в преобразованном к каноническому виду

Они по RFC могут хранится в другом?

Только вот в описаниях к функциям hh_add и hh_parse ничего подобного нет.

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

рано или поздно «стрельнет», когда константа -3 перестанет использоваться и будет заменена на что-то другое.

Вот это и есть «так принято». Сколько было примеров в вашей жизни, когда числовой код ошибки менялся и старый заменялся на что-то другое? Типа, а давайте в новой версии протокола HTTP вместо 404 использовать 4004.

шансов выжить при сопровождении больше.

Если вдруг всё-таки решили изменить значение кода ошибки и библиотека одной версии, а программа другой, ошибку будешь искать гораздо дольше. Потому что в описании библиотеки «возвращает HH_PARSE_BAD_VALUE», а то, что программа при сравнении использует другое значение HH_PARSE_BAD_VALUE совершенно незаметно. А когда написано «возвращает -3», а при изменении версии «с версии 42.0 возвращает -33», то заметить гораздо проще.

И цикл может быть переписан как-то так:

Тут уже вопрос вкуса. Мне 4 строки быстрее понять, чем 15. И сообразить, будет ли преобразовываться «123name» в «123Name» или «nameOk» в «NameOk», проще с ow, чем с «очередное слово начато».

Вы же сами сообщением выше написали, что он не хуже сишного енума

Вы увидели в моих словах что-то глубоко свое.

Я говорил о том, что в Си убогий enum который не дает никаких гарантий, поэтому в чистом Си можно запросто написать вот так:

enum f1_result { a, b, c, d };
enum f2_result { e, f, g };

f1_result f1();

f2_result f2();

if( e == f1() ) { ... }

и компилятор никак не подскажет, что ошибка допущена. Поэтому в Си что использование enum-а, что использование define-ов – это все из одной и той же оперы.

Где в показанном вами комментарии указание RFC?

А оно там и не нужно. Можно, конечно, сослаться и это будет хорошо. Но не обязательно.

Вот пояснить что делает говноцикл – надо. Минимальный пример того, как это сделать без лишних усилий я привел. Он вам не нравится? Ну попрыгайте.

Использование процедуры hh_parse, её ограничения и допущения пишутся в документации, а не в тексте процедуры.

Покажите документацию на hh_parse.

Значит особого случая нет.

Правда? Откуда это известно?

Они по RFC могут хранится в другом?

По RFC имя заголовка представляется token-ом, а token определяется в RFC так:

       token          = 1*<any CHAR except CTLs or separators>
       separators     = "(" | ")" | "<" | ">" | "@"
                      | "," | ";" | ":" | "\" | <">
                      | "/" | "[" | "]" | "?" | "="
                      | "{" | "}" | SP | HT

Т.е. по RFC токен не обязательно нужно форматировать в виде Pascal-Case.

Сколько было примеров в вашей жизни, когда числовой код ошибки менялся и старый заменялся на что-то другое?

В моей жизни было много случаев когда коды удалялись. Типа была ошибка INVALID_FORMAT, ее заменили на несколько других кодов. За счет того, что идентификатор INVALID_FORMAT исчез, старый код, который был на него завязан, перестал компилироваться.

А если бы вместо именованной константы INVALID_FORMAT в коде было бы захардкожено, скажем, -145, то компилятор бы даже и не пискнул.

А еще бывали случаи, когда менялись типы, с помощью которых коды ошибок возвращались. Типа был int, стала структура с двумя полями. Или наоборот. Когда все на именнованных константах, такие смены типов проходят незаметно.

Если в вашей работе такого никогда не было, то может у вас просто опыта не хватает, чтобы рассуждать об этой теме?

Если вдруг всё-таки решили изменить значение кода ошибка и библиотека одной версии, а программа другой, ошибку будешь искать гораздо дольше. Потому что в описании библиотеки «возвращает HH_PARSE_BAD_VALUE», а то, что программа при сравнении использует другое значение HH_PARSE_BAD_VALUE совершенно незаметно.

«Да что ты, черт возьми, такое несешь?» (c)

А когда написано «возвращает -3», а при изменении версии «с версии 42.0 возвращает -33», то заметить гораздо проще.

Вы точно программист?

И сообразить, будет ли преобразовываться «123name» в «123Name» или «nameOk» в «NameOk», проще с ow, чем с «очередное слово начато».

Как я и говорил, наличие Lisp-а в анамнезе негативно сказывается на адекватности.

Вы, кстати говоря, так и не ответили, есть ли в открытом доступе ваш код на Си? Очень уж интересно взглянуть на то, как пишут настолько прошаренные специалисты. Вдохновиться, так сказать?

Я говорил о том, что в Си убогий enum который не дает никаких гарантий, поэтому в чистом Си можно запросто написать вот так:

Да. А значит комментарий не хуже этого enum. define определённо хуже, так как тогда надо угадывать какой define результатам какой функции соответствует.

Т.е. по RFC токен не обязательно нужно форматировать в виде Pascal-Case.

Этот RFC по набору возможных символов с обсуждаемой hh_parse мало коррелирует.

Правда? Откуда это известно?

Из отсутствия комментария. Также, как отсутствие сообщений при работе утилиты командной строки подразумевает штатное завершение без ошибок.

Если в вашей работе такого никогда не было, то может у вас просто опыта не хватает, чтобы рассуждать об этой теме?

Или в моей работе другой набор «так принято». Добавление кодов ошибок было. Переиспользование старых ни разу не помню.

Зато было пару раз «уточнение имён». Условно, вместо INVALID_FORMAT сделали с тем же кодом и смыслом INVALID_FILE_FORMAT.

«Да что ты, черт возьми, такое несешь?» (c)

Запусти бинарник от одного Linux на другом, узнаешь. Там, правда, не про коды ошибок, но слом ABI регулярно. А смена числового кода ошибки это всегда слом ABI. И если он не прописан явно в документации, это часто ведёт к проблемам. Всё равно, что в очередной версии Linux сказать, что теперь сигнал 9 не SIGKILL, а SIGHUP.

Вы, кстати говоря, так и не ответили, есть ли в открытом доступе ваш код на Си?

На Си нет. На других языках есть: https://github.com/Kalimehtar

Да. А значит комментарий не хуже этого enum.

Блин, когда кажется, что вы уже достигли дна, вы начинаете усиленно копать.

facepalm.jpg

Этот RFC по набору возможных символов с обсуждаемой hh_parse мало коррелирует.

Этот RFC относится к HTTP, а кусок кода для иллюстрации качества кода от firkax взят, внезапно, из HTTP(s) прокси. Так что если HTTP-шный RFC к hh_parse из HTTP-прокси не относится, то… Даже не знаю о чем тут дальше говорить.

Из отсутствия комментария.

Из остутствия комментария следует только факт отсутствия комментария. Вы сказали, что о чем-то говорят типы в определении функции hh_parse. Но как раз типы-то ни о чем существенном не говорят. Можно строить предположения, что возвращенный указатель подлежит ручному освобождению. Но ведь уверенности нет, вдруг там какой-то пул памяти применяется в hh_add (из которого hh_parse вызывается). И на счет допустимости передачи NULL в качестве указателя типы ничего не говорят.

Все эти детали на момент написания кода знает автор. Но стороний человек этого не знает. Для этого нужны пояснения, которых нет.

Или в моей работе другой набор «так принято»

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

Запусти бинарник от одного Linux на другом, узнаешь.

Это, мать-мать-мать, настолько другое, что даже понимать не надо.

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

Здесь вообще предмета разговора нет.

А вот то, что вы этот офтопик тянете в разговор о понятности и сопровождаемости кода – вот это еще раз подчеркивает вашу неадекватность.

В коде, вроде бы, затесалась ошибка. Вместо:

    // Если очередное слово начато, то прописные буквы
    // нужно заменять строчными.
    if( word_started ) name[n] = c - 'A' + 'a';

надо бы:

    // Если очередное слово начато, то прописные буквы
    // нужно заменять строчными.
    if( word_started ) name[n] = c - 'A' + 'a';
    else word_started = 1;

Согласен что можно было сделать define на коды ошибок. Про комментарий перед циклом - на мой взгляд и без него очевидно что там делается, но если уж его писать то не в 4 строки а в одну. Что означало ow не помню, буква w видимо от word. word_started не согласен, оно сожрёт кучу места на экране, и ради локализованного на 6 строчках использования делать это нецелесообразно. Если бы оно было раскидано по разным частям функции то можно было бы.

Он ничего не указывает. Из типа даже не видно, можно ли туда отдать NULL (скажем, если нас интересует только имя, но не интересует значение).

hh_parse надо было сделать static, она используется только из одного места которое рядом. Разделение на две функции исключительно для повышения понятности.

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

Поэтому никто особо не заморачивается ни с форматами, ни в целом с документацией к коду. Насколько ворам удобно будет воровать код никого из вменяемых людей не волнует.

Если не ошибаюсь у вас нет опыта в разработке проектов.
В противном случае ваш пост был бы о другом.

у вас нет опыта в разработке проектов.

Проектов по осуществлению/оправданию/покрыванию воровства? Очевидно нет.

< Проектов по осуществлению/оправданию/покрыванию воровства? Очевидно нет.

А как же open source проекты?

Документация к коду служит ровно одной цели - упростить воровство этого кода.

Мои проекты хорошо документированы.
Конечно тривиальный код не документирован, но иногда и к блоку строк такого рода имеется комментарий для того, чтобы не тратить время на просмотр кода и траты времени на понимание его прелназначения.
…
Вообщем комментарии полезны в первую очередь разработчику проекта.

Что касаемо воровства чужого кода, то многие программисты весьма ленивы и просто поленятся развивать код, …

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

А как же open source проекты?

Созданные под известно какими лицензиями и предназначенные для юридической легализации воровства? Опять же, нет.

Созданные под известно какими лицензиями и предназначенные для юридической легализации воровства? Опять же, нет.

Т.е. те кто использует open source код воры?
Какую же другую модель open source предлагаете?

Т.е. те кто использует open source код воры?

Т. е. те, кто оправдывает воровство и потворствует ему воры.

Т. е. те, кто оправдывает воровство и потворствует ему воры

Понятно.
Просто вбросили.

Использую ASCIIDOC - маркдаун абсолютно тупой формат, я против него. А в asciidoc есть вообще всё, а чего нет, реализуется расширениями - например, встроенные dia и plantuml (и эти расширения всегда есть в asciidoc)

Понятно. Попытался пару раз подменить понятия. Далее после неудач поломался и начал заспам совсем ясельными лозунгами.

• «нет опыта» -> «все в отрасли воруют, а кто не ворует - тот не в отрасли»
• «опенсорц» -> «опенсорц код более свободен, чем гнутый, потому как не запрещает его воровать» -> «истинная свобода предполагает и поощряет воровство»
• «а что ты предлагаешь» -> «а как же тогда жить, если не воровать»
• «ты просто вбросил» -> «я слишком ограничен, чтобы рассуждать на данную тему, поэтому любой кто отличается от меня - шиз/троль»

Нестареющая классика.

Блин, когда кажется, что вы уже достигли дна, вы начинаете усиленно копать.

Вам логические выводы недоступны? Только эмоциональные оценки.

Из остутствия комментария следует только факт отсутствия комментария.

У любого проекта есть некие общепроектные правила. Эти правила никогда не дублируются в комментарии к каждой функции. Но если в каком-то случае их необходимо нарушить, то комментарий обязателен. Поэтому отсутствие комментария = «здесь нет особенностей относительно общих правил».

Для этого нужны пояснения, которых нет.

Эти пояснения нужны не к функции, а к проекту в целом.

А вот то, что вы этот офтопик тянете в разговор о понятности и сопровождаемости кода – вот это еще раз подчеркивает вашу неадекватность.

Поддержка ABI не относится к сопровождаемости? Я утверждал, что для сопровождаемости старые коды ошибок не могут быть переиспользованы (и поэтому, в частности, на эти коды можно опираться). Вы пишете, что в ваших проектах это норма. Какая сопровождаемость?

И про понятность. Если бы имена были понятнее, но встречался бы код

        //URL:DELETE /api/employee/1
        [HttpDelete("{id}")]
        public ActionResult<Employee> DeleteEmployee(int id)
        {
            var employee = Employees.FirstOrDefault(emp => emp.Id == id);
            if (employee == null)
            {
                // 404 Not Found if the employee does not exist
                return NotFound();
            }
            // Delete the employee
            Employees.Remove(employee);
            return Ok(employee); // 200 OK with the deleted employee's details
        }

То есть в комментарии здесь приходится указывать 404 и 200, так как они понятнее, чем NotFound и Ok.

Если бы вместо

return Ok(employee); // 200 OK with the deleted employee's details

было написано

return Status(200, employee); // deleted employee's details

то информации было бы столько же, но читать для её получения заметно меньше.

Нестареющая классика.

Наверное не понял о чём вы хотели сказать.
Извините.

Вам логические выводы недоступны? Только эмоциональные оценки.

Мне остается только эмоционально оценивать неадекватность с вашей стороны.

Поддержка ABI не относится к сопровождаемости?

Сопровождаемости исходного кода? Насколько я понимаю понятие ABI – нет, не относится.

Я утверждал, что для сопровождаемости старые коды ошибок не могут быть переиспользованы (и поэтому, в частности, на эти коды можно опираться).

Еще раз повторюсь: очень вероятно, что ваш опыт весьма ограниченный.

Вы пишете, что в ваших проектах это норма.

У вас картина мира, похоже, состоит из каких-то примитивных вещей. Типа вот есть либо, скажем, libcurl. Еще когда-то выпустили в свет и теперь во имя совместимости новые версии libcurl делают так, чтобы ничего не поломать в коде, который libcurl использует. Поэтому если кто-то у себя вместо CURLE_NOT_BUILD_IN записал в коде число 4, то это безопасно, т.к. в libcurl это значение переиспользовать не будут.

Только вот либы, подобные libcurl, – это самый мизер от того объема кода, который разрабатывается в разных закрытых проектах. И в которых сегодня написали модуль featureA, а завтра его перелопатили и в хвост, и в гриву. И делали, и перелопачивали featureA под текущие нужды, что нужно было сейчас, то и сделали. А что не нужно – выбросили нафиг. И тут уж полагаться на то, что в первой версии featureA константе X соответствовало значение 44, значит и в новой версии будет значение 44, несколько наивно.

Так что да, и меняются, и выбрасываются только в путь. Особенно когда используются enum-ы. Был enum f1_result { a, b, c, d }; стал enum f1_result { a, c, c2, c3, d, e, f };. И никого не парит что там числовые значения для c и d куда-то съехали.

То есть в комментарии здесь приходится указывать 404 и 200, так как они понятнее, чем NotFound и Ok.

Я без понятия зачем в этом коде записаны такие комментарии. ActionResult же не является синонимом status line из протокола HTTP. Значит трансформация NotFound и Ok в коды HTTP ведется на другом уровне абстракции. А на уровне метода DeleteEmployee значение имеет именно NotFound и Ok. Может там выше будет идти трансляция NotFound в код 404, или в код 410. А на Ok могут выдать как 200, так и 202.

Сопровождаемости исходного кода? Насколько я понимаю понятие ABI – нет, не относится.

Если код больше, чем в одном файле, то относится.

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

Для Си универсальным было бы что-то вроде:

extern const char* hh_parse_too_many_headers; // с определением значений в отдельном файле
...

// ret. NULL = ok; hh_parse_too_many_headers; hh_parse_too_long_header_name; hh_parse_bad_header_name; hh_parse_too_long_header_value; hh_parse_missing_colon
const char* hh_parse(...) ...

но так не принято. Поэтому лучше целые числовые коды ошибок.

И в которых сегодня написали модуль featureA, а завтра его перелопатили и в хвост, и в гриву. И делали, и перелопачивали featureA под текущие нужды, что нужно было сейчас, то и сделали. А что не нужно – выбросили нафиг.

И вы считаете, что это норма и при проектировании и документировании надо равняться на такие проекты?

Может там выше будет идти трансляция NotFound в код 404, или в код 410. А на Ok могут выдать как 200, так и 202.

Вот именно для этого приходится писать эти комментарии. Чтобы было понятно, чего ожидать от этой строки в данном месте.

Зависит от ТЗ по простоте, безопасности, красивости, легкости развертывания/восстановления.

Markdown - сам по себе это язык форматирования текста, как и html.

Нужен редактор, читалка, ифраструктура для хранения и обеспечения доступа.

Я например, для коротких «сырых» заметок использую joplin, файлики в котором синхронизируется между несколькими устройствами (и смартфоном).

Для чего-то посерьезнее - kate/codium (они умеют показывать md без тегов), а через git, пушится на хоум gitlab-сервер.

Вариант удобнее, наглядней и безопасней (а это не точно) - https://www.mediawiki.org/wiki/MediaWiki/ru Разворачивается в 2 команды, читаешь/редактируешь из браузера.

obsidian - наше усё!

Документация?
Это в сказке про Золушку.
Вот послушайте, что разработчик 1С пишет.

https://catalog.mista.ru/1c/articles/2530832/

На последнем месте работы, когда я туда пришёл, было 20 расширений без описания и комментариев, 55 баз Бухгалтерии и 15 ЗУП. 
О том, что их столько, я узнал лишь недели через три. 
Видимо, побоялись сказать сразу, чтобы я не убежал. 
Меня одного сразу посадили и на Бухгалтерию, и на ЗУП.

Почему так - понятно.
Так многие программисты поступают.
Вообщем «человеческий фактор».

Это реальность того, что имеется в жизни, а не о красивых суждениях о хорошей документации.

У каждого свой подход.

Ещё.

Человеку пол года платили хорошую зарплату, за что?
Это не упрёк программисту.