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

9

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

Мировой инженер
источник
1
Очевидно, это во многом будет зависеть от того, говорите ли вы о математической или архитектурной сложности. Они не документированы вообще одинаково. Что он?
Эдвард Стрендж
2
related: где программист должен объяснить расширенную логику кода? , Мне особенно нравится подход «тесты как документ», предложенный в одном из ответов.
комнат
1
@ Гнат, почему спасибо. Я думаю, что в целом мой ответ на этот вопрос сработает и для этого вопроса.
Марк Бут
@ MarkBooth правильно, это был в основном ваш ответ, который я имел в виду, когда предлагал связанный вопрос. Ответ, в общем, хороший, но вопрос о тестах особенно прозвенел, поскольку я использовал его один раз для реализации одного особенно сложного алгоритма.
gnat

Ответы:

8

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

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

Хорошим примером может служить работа по нечеткому сопоставлению текста. Я провел серьезное исследование алгоритмов и реализовал так называемый «алгоритм Смита-Уотермана» (который фактически используется для последовательностей ДНК, но в целом применяется к «сопоставлению»). Поэтому вместо того, чтобы просто реализовать алгоритм, я нашел ссылки в Интернете и включил одну или две ссылки. Как и выше, это демонстрирует, что (а) мой алгоритм соответствует опубликованному алгоритму, и (б) алгоритм был рассмотрен и показан для работы.

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

Кирк Бродхерст
источник
3

Комментарии, касающиеся источника, - это первое, что вы должны сделать. Это гарантирует, что есть прямая ссылка на документацию прямо по коду. Если документация очень сложная, рассмотрите возможность размещения только резюме в комментариях, а затем ссылку на какой-нибудь внешний документ, который содержит более полное описание архитектуры / сложного алгоритма. Однако, если это не слишком сложно, рассмотрите возможность объединения всей документации в одном месте. Это максимизирует вероятность того, что ваш код / ​​документация останутся синхронизированными и будут прочитаны вместе.

Oleksi
источник
0

Документируйте код в той мере, в которой это требуется вашей команде / компании. Если младший Dev будет требоваться для поддержки кода, возможно, вам придется подробно остановиться на некоторых из математики. Это решение руководства, и они должны дать вам необходимое время.

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

Вы не должны делать поиск в Интернете для них.

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