Успокой мой пьяный разум многоликая река. Пусть отныне вдохновляют лишь камни да вода.
Здравствуй, дорогой дневник.
На работе упомянули про документацию кода, бо "скоро Urban knight уйдет на питон-мидла, и как вообще работать новому?". И не смотря на то, что вакансия BI аналитика в Шереметьеве так манит, а в процессах такой бардак, я пока не ухожу.
Но! Вопрос про документацию - очень важный.
Когда открываешь код, а там какими-то странными методами достигается результат, не всегда ясно почему сделано именно так. Может быть автор не знает, что можно сделать иначе-удобнее? Или наоборот, автор знает что-то такое, почему делать нужно именно так, а не иначе...
Совсем странно себя ощущаю, когда автор кода - я, но 2 года назад.
Для решения такой проблемы придуманы комментарии и штуки, которые называются docstring. Примерно вот такие:
def add(a, b):
"""
Суммирует два числа.
Args:
a (int): Первое число
b (int): Второе число
Returns:
int: Сумма двух чисел
"""
return a + b
И всё сразу понятно. Что делает эта штука, зачем оно. Что на входе и выходе. Огонь же.
Вот.
Нужно сделать автодокументацию для рабочего проекта. Задачка-то проста.
1. Просканировать папку с проектом на наличие питоновских файлов.
2. В каждом файле поискать функции, классы. В каждом из них - поискать docstring и комментарии начинающиеся на TODO.
3. Собрать в отчет-файл "для менеджеров"
И ведь, зараза, если поискать готовые решения - поголовно рекомендуют sphinx. Я почти день с ним разбирался, что там и как. По какой-то непонятной причине, большинство обучалок и статей на хабре включают в себя установку, запуск, генерацию пустого html. Всё. Не готового html с нужными данными, нет. Html с заглушкой и на этом всё.
В документации на русском плюс-минус тоже самое.
Ну и я понял, что сфингс этот содержит ФАТАЛЬНЫЙ недостаток. Он непонятный.
Что нужно сделать, когда что-то работает непонятно? Правильно, написать своё и понятное.
Буквально до обеда, паралелльно с вышивкой и рыбалочкой я набросал скрипт который... Делает ровно то, что я написал. Ищет функции, докстринги, тудушки и складывает в один файл-результат.
Даже добавил красных-зеленых штучек, чтобы дорого-богато.
На работе упомянули про документацию кода, бо "скоро Urban knight уйдет на питон-мидла, и как вообще работать новому?". И не смотря на то, что вакансия BI аналитика в Шереметьеве так манит, а в процессах такой бардак, я пока не ухожу.
Но! Вопрос про документацию - очень важный.
Когда открываешь код, а там какими-то странными методами достигается результат, не всегда ясно почему сделано именно так. Может быть автор не знает, что можно сделать иначе-удобнее? Или наоборот, автор знает что-то такое, почему делать нужно именно так, а не иначе...
Совсем странно себя ощущаю, когда автор кода - я, но 2 года назад.
Для решения такой проблемы придуманы комментарии и штуки, которые называются docstring. Примерно вот такие:
def add(a, b):
"""
Суммирует два числа.
Args:
a (int): Первое число
b (int): Второе число
Returns:
int: Сумма двух чисел
"""
return a + b
И всё сразу понятно. Что делает эта штука, зачем оно. Что на входе и выходе. Огонь же.
Вот.
Нужно сделать автодокументацию для рабочего проекта. Задачка-то проста.
1. Просканировать папку с проектом на наличие питоновских файлов.
2. В каждом файле поискать функции, классы. В каждом из них - поискать docstring и комментарии начинающиеся на TODO.
3. Собрать в отчет-файл "для менеджеров"
И ведь, зараза, если поискать готовые решения - поголовно рекомендуют sphinx. Я почти день с ним разбирался, что там и как. По какой-то непонятной причине, большинство обучалок и статей на хабре включают в себя установку, запуск, генерацию пустого html. Всё. Не готового html с нужными данными, нет. Html с заглушкой и на этом всё.
В документации на русском плюс-минус тоже самое.
Ну и я понял, что сфингс этот содержит ФАТАЛЬНЫЙ недостаток. Он непонятный.
Что нужно сделать, когда что-то работает непонятно? Правильно, написать своё и понятное.
Буквально до обеда, паралелльно с вышивкой и рыбалочкой я набросал скрипт который... Делает ровно то, что я написал. Ищет функции, докстринги, тудушки и складывает в один файл-результат.
Даже добавил красных-зеленых штучек, чтобы дорого-богато.