Код — это и есть дизайн (design, а не наше дизайн как оформление) продукта. По коду его можно создать и модифицировать. А по любой другой документации продукт придется заново разрабатывать.
КД — это комплект документации, позволяющий воспроизвести продукт. Для электронного продукта это, например, схема, чертежи плат, корпуса, etc. Для программного — это исходный код и все, что необходимо для его сборки (скрипты сборки, etc). Вся остальная документация может присутствовать, но необходимой является только сам программный код.
Ну и как и любая документация, код может быть хорошо читаемый, а может быть и говно (ту же STM хают за через задницу написанные доки на МК, то же самое и с говнокодом).
А зачем закрывать разработку? Подними публичную разработку на гитхабе. Он заодно позволяет приходить с запросом «а дайте мне доступ на запись» уже не с пустыми руками, а своим форком.
P.S. Говнокод, как бы он правильно не был написан — это не инженерия и не конструирование. Нужна нормальная конструкторская документация «для людей»
Код — это и есть исчерпывающая конструкторская документация. Те, кто пытается накрутить на это еще какую-то КД добром обычно не кончают. Ну, кроме тех, кому нужна абсолютно безбажная программа за любые деньги и время, и то вопрос, насколько это эффективно.
Разработчики — не пользователи. Любой разработчик пользуется только одной документацией — содержимым своей памяти. Создавать документацию на код — это тратить 70% времени не на собственно создание программы. При этом обученные оной документацией посторонние разработчики в принципе не дадут потерянные 70% работы. А ввести новичка — куда дешевле потратить 100% времени в течение двух недель на его обучение, чем 70% в течение всей жизни проекта.
Так что тебе дали код — исчерпывающую документацию на продукт и свободу его менять. Этого достаточно.
Ну если тебе лень разбираться в проекте, который хочешь дополнить — тебе и собственно дополнять так же лень будет.
И еще, зачем ты отвечаешь сам себе, хоть по контексту больше похоже на ответ мне?
Таки нет. Пользователя не интересует устройство черного ящика — только как он себя ведет и как с ним взаимодействовать. Разработчику напротив, нужно глубоко вникать в поведение.
Да и в твоем примере ты описываешь скорее не документацию, а учебник по написанию RTOS.
Это у лекции-то усвояемость 68%? И близко нет. В лучшем случае 30% — первые 15% и последние 15%. В тексте, к тому же, куда проще вернуться к непонятым местам. Усвояемость у текста при вдумчивом чтении как раз может приблизиться процентам к 80-90.
К тому же, читаю я раз в 5-10 быстрее, чем нормальный человек говорит (забудем пока про Эксель и Пуни Пуни Поэми). Так что плотность подачи текстом куда выше — за то же время я прочитаю в 5-10 раз больше, чем может начитать лектор.
Только его нынче в 99% случаев пишет не человек, так что для человека он не читаем. А так — раньше в нем и программировали.
А так по дизасму зачастую можно вполне неплохо понять, что делает программа. Только медленно это — выпиливаются практически все документирующие свойства исходного кода, а самого кода становится больше.
Участвовал. Не скажу правда про размер, но думаю 100к там было. А вот доков не было. Да и не особо они нужны, кроме как на архитектуру — ее пришлось выяснять у остальных участников и ковырянием кода.
Так что отсутствие документации — скорее отговорки своей лени или некомпетентности.
Одно из очень редких исключений — сложные алгоритмы типа компрессии, причем сильно оптимизированные до полной нечитаемости в угоду производительности.
Ну это и есть «зубодробительные конструкции», как я понимаю.
Ну и против комментариев к интерфейсной части я все же ничего не имею. Хотя возможно ты и прав.
В стандарте довольно сложно найти требуемое, но, например, это говорится в завалявшемся у меня стандарте C99:
5.2.4.2.1 Sizes of integer types <limits.h>
The values givenbelowshall be replaced by constant expressions suitable for use in #if
preprocessing directives.… Their implementation-defined values shall be equal or greater in magnitude (absolute value) to those shown, with the same sign.
…
—minimum value for an object of type int INT_MIN -32767 // −(2^15 − 1)
—maximum value for an object of type int INT_MAX +32767 // 2^15 − 1
Для остальных знаковых целочисленных типов тоже указаны симметричные диапазоны.
Ну и как и любая документация, код может быть хорошо читаемый, а может быть и говно (ту же STM хают за через задницу написанные доки на МК, то же самое и с говнокодом).
Так что тебе дали код — исчерпывающую документацию на продукт и свободу его менять. Этого достаточно.
И еще, зачем ты отвечаешь сам себе, хоть по контексту больше похоже на ответ мне?
Да и в твоем примере ты описываешь скорее не документацию, а учебник по написанию RTOS.
К тому же, читаю я раз в 5-10 быстрее, чем нормальный человек говорит (забудем пока про Эксель и Пуни Пуни Поэми). Так что плотность подачи текстом куда выше — за то же время я прочитаю в 5-10 раз больше, чем может начитать лектор.
А так по дизасму зачастую можно вполне неплохо понять, что делает программа. Только медленно это — выпиливаются практически все документирующие свойства исходного кода, а самого кода становится больше.
Так что отсутствие документации — скорее отговорки своей лени или некомпетентности.
Ну и против комментариев к интерфейсной части я все же ничего не имею. Хотя возможно ты и прав.
Для остальных знаковых целочисленных типов тоже указаны симметричные диапазоны.