Правильное место для документирования реализации сложного кода
Последние 3 месяца я работаю над сольным проектом в компании. Поскольку по большей части моя работа состояла из кодирования, я, естественно, сгенерировал некоторый объем кода (около 2000 строк), который я старался комментировать как можно деликатнее.
В этом проекте я использовал много абстрактных концепций Python, и в одной части проекта я интенсивно использовал первоклассные функции. В этой части я динамически генерирую функции из других функций и сохраняю их для дальнейшего использования. Теперь, хотя мои идеи здравы и просты для понимания на бумаге, когда код читается, это не понятно. Несмотря на наличие документооборота, моим начальникам было трудно следовать коду, даже в моем присутствии и в пошаговом руководстве. Теперь мой вопрос касается документации такого кода. Один пример выглядит следующим образом и является частью закрывающей функции (таким образом, temp является внутренней функцией):
def temp(time, var, ground_truth):
mean = ground_truth(time)
noisy = np.random.normal(mean, var)
return noisy
# ground_truth refers to vector of functions which are to be manipulated
for _ in range(num_points + 1):
new_tuple = list()
for i in range(len(ground_truth)):
partial = functools.partial(temp, var=variances[i], ground_truth=ground_truth[i])
new_tuple.append(partial)
Приведенный выше код берет список функций, и из каждой функции списка генерируется новая функция, которая представляет собой сумму старой функции плюс случайно сгенерированное нормально распределенное значение.
Мой вопрос касается правильного размещения документации по реализации и подробных идей кода. Правильно ли включать такую подробную документацию в строку документации или следует создать совершенно отдельный документ специально для таких деталей, касающихся реализации? Если должен быть создан отдельный документ, каков наилучший путь к нему и есть ли общие рекомендации?
Пожалуйста, имейте в виду, что это программное обеспечение должно быть передано моим руководителям, и они должны продолжить его разработку.