Идеальная система документирования кода
От: AndrewVK Россия http://blogs.rsdn.org/avk
Дата: 27.12.09 17:49
Оценка:
Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
AVK Blog
Re: Идеальная система документирования кода
От: minorlogic Украина  
Дата: 27.12.09 18:03
Оценка: 1 (1) +1
Здравствуйте, AndrewVK, Вы писали:

AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.


В полном идеале лучше ьез документирования, чтобы язык позволял максимально ясно передать то что хотел сделать програмист.
... << RSDN@Home 1.2.0 alpha 4 rev. 1237>>
Ищу работу, 3D, SLAM, computer graphics/vision.
Re: Идеальная система документирования кода
От: Cyberax Марс  
Дата: 27.12.09 18:06
Оценка:
Здравствуйте, AndrewVK, Вы писали:

AVK>Хотелось бы обсудить сабж.

Его не существует...

Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki. Куда можно было бы вставлять схемы, рисунки, screenshot'ы. И чтоб оно всё версировалось вместе с кодом с помощью одной SCM.

И чтоб компилятор проверял битые ссылки.

И ещё хочу пони.
Sapienti sat!
Re: Идеальная система документирования кода
От: nikov США http://www.linkedin.com/in/nikov
Дата: 27.12.09 18:13
Оценка:
Здравствуйте, AndrewVK, Вы писали:

AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.


Обычно сейчас в наличии такие варианты:
* читать/редактировать комментарии в коде, причем всё форматирование будет в виде сырого языка разметки, объёмная документация вытесняет код с экрана, так как находится в том же окне
* смотреть комментарии к элементам кода в виде всяких всплывающих подсказок (по наведению мыши/клавиатурному шорткату), никакого редактирования, (иногда) примитивная навигация
* построить отдельный файл HTML-документации, и изучать его. Нет автоматической синхронизации с положением в коде, нельзя напрямую отредактировать, при обновлении комментариев в коде документация не обновляется автоматически

Что иногда хотелось бы (особенно при попытках изучить малознакомый код, написать какие-то заметки для себя и будущих поколений):
* Красиво отформатированная документация в отдельном окошке внутри IDE, которая умеет автоматически синхронизироваться с элементом кода, на котором находится курсор, в которой можно делать закладки, есть удобная навигация и которую можно редактировать прямо в режиме rich text.
Re: Идеальная система документирования кода
От: NikeByNike Россия  
Дата: 27.12.09 19:03
Оценка: +1
Здравствуйте, AndrewVK, Вы писали:

AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.

1. Живой человек который изучит систему и буде отвечать на все вопросы
2. Документация которая построится сама по коду

Если серьёзно, был бы полезен критерий:
Источник данных для системы документирования не должен захламлять код, но должен оставлять в нём краткие комментарии со ссылкой на полные и перекрёстные.
Нужно разобрать угил.
Re[2]: Идеальная система документирования кода
От: nikov США http://www.linkedin.com/in/nikov
Дата: 27.12.09 19:21
Оценка:
Здравствуйте, Cyberax, Вы писали:

C>Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki. Куда можно было бы вставлять схемы, рисунки, screenshot'ы. И чтоб оно всё версировалось вместе с кодом с помощью одной SCM.


Но чтобы можно было посмотреть историю для кода и документации раздельно. То есть скрыть правки, где менялся только код или только документация.
Re[3]: Идеальная система документирования кода
От: Cyberax Марс  
Дата: 27.12.09 19:28
Оценка:
Здравствуйте, nikov, Вы писали:

C>>Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki. Куда можно было бы вставлять схемы, рисунки, screenshot'ы. И чтоб оно всё версировалось вместе с кодом с помощью одной SCM.

N>Но чтобы можно было посмотреть историю для кода и документации раздельно. То есть скрыть правки, где менялся только код или только документация.
По идее, это обычная функциональность нормальных VCS...
Sapienti sat!
Re[2]: Идеальная система документирования кода
От: AndrewVK Россия http://blogs.rsdn.org/avk
Дата: 27.12.09 20:10
Оценка: +1
Здравствуйте, minorlogic, Вы писали:

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


Это нереально, по крайней мере в ближайшем будущем. Чем высокоуровневей концепция, тем менее ее видно из голого кода.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
AVK Blog
Re[2]: Идеальная система документирования кода
От: AndrewVK Россия http://blogs.rsdn.org/avk
Дата: 27.12.09 20:10
Оценка:
Здравствуйте, Cyberax, Вы писали:

AVK>>Хотелось бы обсудить сабж.

C>Его не существует...

Я в курсе. Но мне было бы все таки интересно, в какую сторону имеет смысл копать.

C>Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki.


А наоборот?

C> Куда можно было бы вставлять схемы, рисунки, screenshot'ы.


Куда, в код? А редактировать как?

C> И чтоб оно всё версировалось вместе с кодом с помощью одной SCM.


Это понятно.

C>И чтоб компилятор проверял битые ссылки.


Именнно компилятор?

C>И ещё хочу пони.


Это шутка?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
AVK Blog
Re[2]: Идеальная система документирования кода
От: AndrewVK Россия http://blogs.rsdn.org/avk
Дата: 27.12.09 20:10
Оценка:
Здравствуйте, nikov, Вы писали:

N>Что иногда хотелось бы (особенно при попытках изучить малознакомый код, написать какие-то заметки для себя и будущих поколений):

N>* Красиво отформатированная документация в отдельном окошке внутри IDE, которая умеет автоматически синхронизироваться с элементом кода, на котором находится курсор

Именно в отдельном окошке? Или какие то еще приемлемые варианты есть?

N>, в которой можно делать закладки


В каком виде закладки и как их использовать?

N>, есть удобная навигация и которую можно редактировать прямо в режиме rich text.


В смысле прямо в редакторе кода? А как конкретно — всплывающие модальные окна, распахивающиеся блоки в редакторе, как то еще?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
AVK Blog
Re[2]: Идеальная система документирования кода
От: AndrewVK Россия http://blogs.rsdn.org/avk
Дата: 27.12.09 20:10
Оценка:
Здравствуйте, NikeByNike, Вы писали:

NBN>1. Живой человек который изучит систему и буде отвечать на все вопросы


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

NBN>2. Документация которая построится сама по коду


Это здорово. Вопрос в том, как. В примитивном виде это уже есть даже для С++, но что то оно не особо популярно постфактум.

NBN>Источник данных для системы документирования не должен захламлять код, но должен оставлять в нём краткие комментарии со ссылкой на полные и перекрёстные.


Раскрыть мысль не хочешь?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
AVK Blog
Re: Идеальная система документирования кода
От: dekart  
Дата: 27.12.09 20:29
Оценка:
Здравствуйте, AndrewVK, Вы писали:

AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.


doxygen.org давно ответил на все вопросы.
Re[3]: Идеальная система документирования кода
От: Anton Batenev Россия https://github.com/abbat
Дата: 27.12.09 20:30
Оценка:
Здравствуйте, nikov, Вы писали:

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


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

Но есть одна большая проблема — документацию надо писать и поддерживать. А против "некогда тратить время — надо код писать" не поможет никакая идеальная система
avalon 1.0rc2 rev 305, zlib 1.2.3
Re[3]: Идеальная система документирования кода
От: nikov США http://www.linkedin.com/in/nikov
Дата: 27.12.09 20:30
Оценка:
Здравствуйте, AndrewVK, Вы писали:

AVK>Именно в отдельном окошке? Или какие то еще приемлемые варианты есть?


Да, я бы предпочел в отдельном окошке сбоку от кода. Это удобно, когда есть широкий экран (или два широких экрана )
И вообще, я бы предпочел, чтобы документация хранилась в отдельных XML файлах, и в коде были бы самое большее ссылки на них в комментариях. Чтобы система контроля версия могла легко различить, где правки в коде, а где в документации. И чтобы не заботиться сворачиванием/разворачиванием этой документации. Конечно, в некоторых местах кода могут встречаться короткие комментарии прямо внутри методов.

N>>, в которой можно делать закладки

AVK>В каком виде закладки и как их использовать?

Ну букмарки, для навигации. Пометить место, потом туда вернуться.

N>>, есть удобная навигация и которую можно редактировать прямо в режиме rich text.

AVK>В смысле прямо в редакторе кода?

Нет, не в редакторе кода, а сбоку. То есть в отдельной панели, а расположит ее пользователь, как захочет.
Re[2]: Идеальная система документирования кода
От: dekart  
Дата: 27.12.09 20:31
Оценка:
http://doxygen.org — линк не верно прилепился в прошлом сообщении
Re[2]: Идеальная система документирования кода
От: AndrewVK Россия http://blogs.rsdn.org/avk
Дата: 27.12.09 20:35
Оценка:
Здравствуйте, dekart, Вы писали:

D>doxygen.org давно ответил на все вопросы.


Увы, но нет.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
AVK Blog
Re[4]: Идеальная система документирования кода
От: AndrewVK Россия http://blogs.rsdn.org/avk
Дата: 27.12.09 20:40
Оценка:
Здравствуйте, Anton Batenev, Вы писали:

AB>Doxygen позволяет разделять документацию и код по разным файлам


C#, к примеру, тоже. Насчет Java не помню.

AB>Но есть одна большая проблема — документацию надо писать и поддерживать.


Значит надо сделать так, чтобы на поддержание затрачивалось как можно меньше усилий, нет?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
AVK Blog
Re[4]: Идеальная система документирования кода
От: AndrewVK Россия http://blogs.rsdn.org/avk
Дата: 27.12.09 20:40
Оценка:
Здравствуйте, nikov, Вы писали:

N>И вообще, я бы предпочел, чтобы документация хранилась в отдельных XML файлах


Почему XML?

N>>>, в которой можно делать закладки

AVK>>В каком виде закладки и как их использовать?

N>Ну букмарки, для навигации. Пометить место, потом туда вернуться.


Если дока связана с кодом, и в коде букмарки есть, не хватит ли этого?

AVK>>В смысле прямо в редакторе кода?


N>Нет, не в редакторе кода, а сбоку. То есть в отдельной панели, а расположит ее пользователь, как захочет.


Т.е. независимый WYSIWYG редактор?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
AVK Blog
Re[3]: Идеальная система документирования кода
От: AndrewVK Россия http://blogs.rsdn.org/avk
Дата: 27.12.09 20:40
Оценка:
Здравствуйте, dekart, Вы писали:

D>http://doxygen.org — линк не верно прилепился в прошлом сообщении


Не переживай, я в курсе того, что такое доксиген
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
AVK Blog
Re[5]: Идеальная система документирования кода
От: Anton Batenev Россия https://github.com/abbat
Дата: 27.12.09 20:50
Оценка:
Здравствуйте, AndrewVK, Вы писали:

AVK> AB>Но есть одна большая проблема — документацию надо писать и поддерживать.

AVK> Значит надо сделать так, чтобы на поддержание затрачивалось как можно меньше усилий, нет?

В пределе ноль? Но ты сам ниже ответил, что так не бывает.

Если же продолжить разговор про doxygen — им, как и любым инструментом, требуется овладеть. После этого основным усилием на поддержание документации будет усилие заставить себя ее поддерживать. Т.е. пока что до технических проблем самого инструментария мы и не дошли.
avalon 1.0rc2 rev 305, zlib 1.2.3
Подождите ...
Wait...
Пока на собственное сообщение не было ответов, его можно удалить.