Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
В полном идеале лучше ьез документирования, чтобы язык позволял максимально ясно передать то что хотел сделать програмист.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж.
Его не существует...
Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki. Куда можно было бы вставлять схемы, рисунки, screenshot'ы. И чтоб оно всё версировалось вместе с кодом с помощью одной SCM.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Обычно сейчас в наличии такие варианты:
* читать/редактировать комментарии в коде, причем всё форматирование будет в виде сырого языка разметки, объёмная документация вытесняет код с экрана, так как находится в том же окне
* смотреть комментарии к элементам кода в виде всяких всплывающих подсказок (по наведению мыши/клавиатурному шорткату), никакого редактирования, (иногда) примитивная навигация
* построить отдельный файл HTML-документации, и изучать его. Нет автоматической синхронизации с положением в коде, нельзя напрямую отредактировать, при обновлении комментариев в коде документация не обновляется автоматически
Что иногда хотелось бы (особенно при попытках изучить малознакомый код, написать какие-то заметки для себя и будущих поколений):
* Красиво отформатированная документация в отдельном окошке внутри IDE, которая умеет автоматически синхронизироваться с элементом кода, на котором находится курсор, в которой можно делать закладки, есть удобная навигация и которую можно редактировать прямо в режиме rich text.
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
1. Живой человек который изучит систему и буде отвечать на все вопросы
2. Документация которая построится сама по коду
Если серьёзно, был бы полезен критерий:
Источник данных для системы документирования не должен захламлять код, но должен оставлять в нём краткие комментарии со ссылкой на полные и перекрёстные.
Здравствуйте, Cyberax, Вы писали:
C>Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki. Куда можно было бы вставлять схемы, рисунки, screenshot'ы. И чтоб оно всё версировалось вместе с кодом с помощью одной SCM.
Но чтобы можно было посмотреть историю для кода и документации раздельно. То есть скрыть правки, где менялся только код или только документация.
Здравствуйте, nikov, Вы писали:
C>>Было бы удобно, чтобы можно было делать из кода ссылки на что-то типа Wiki. Куда можно было бы вставлять схемы, рисунки, screenshot'ы. И чтоб оно всё версировалось вместе с кодом с помощью одной SCM. N>Но чтобы можно было посмотреть историю для кода и документации раздельно. То есть скрыть правки, где менялся только код или только документация.
По идее, это обычная функциональность нормальных VCS...
Здравствуйте, minorlogic, Вы писали:
M>В полном идеале лучше ьез документирования, чтобы язык позволял максимально ясно передать то что хотел сделать програмист.
Это нереально, по крайней мере в ближайшем будущем. Чем высокоуровневей концепция, тем менее ее видно из голого кода.
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, 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>>
Здравствуйте, nikov, Вы писали:
N>Что иногда хотелось бы (особенно при попытках изучить малознакомый код, написать какие-то заметки для себя и будущих поколений): N>* Красиво отформатированная документация в отдельном окошке внутри IDE, которая умеет автоматически синхронизироваться с элементом кода, на котором находится курсор
Именно в отдельном окошке? Или какие то еще приемлемые варианты есть?
N>, в которой можно делать закладки
В каком виде закладки и как их использовать?
N>, есть удобная навигация и которую можно редактировать прямо в режиме rich text.
В смысле прямо в редакторе кода? А как конкретно — всплывающие модальные окна, распахивающиеся блоки в редакторе, как то еще?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, NikeByNike, Вы писали:
NBN>1. Живой человек который изучит систему и буде отвечать на все вопросы
Живой человек, сам понимаешь, не всегда есть. А когда есть — может послать тебя далеко и надолго. В этом топике меня все таки технические аспекты интересуют.
NBN>2. Документация которая построится сама по коду
Это здорово. Вопрос в том, как. В примитивном виде это уже есть даже для С++, но что то оно не особо популярно постфактум.
NBN>Источник данных для системы документирования не должен захламлять код, но должен оставлять в нём краткие комментарии со ссылкой на полные и перекрёстные.
Раскрыть мысль не хочешь?
... << RSDN@Home 1.2.0 alpha 4 rev. 1324 on Windows 7 6.1.7600.0>>
Здравствуйте, AndrewVK, Вы писали:
AVK>Хотелось бы обсудить сабж. Кто что думает по этому поводу? Интересны любые мысли, причем прежде всего со стороны программистов и архитектов.
Здравствуйте, nikov, Вы писали:
n> Но чтобы можно было посмотреть историю для кода и документации раздельно. То есть скрыть правки, где менялся только код или только документация.
Doxygen позволяет разделять документацию и код по разным файлам, позволяет вставлять картинки, ссылки на внешние и внутренние источники, диаграммы, при сборке документации проверяется наличие файлов, и т.д.
Но есть одна большая проблема — документацию надо писать и поддерживать. А против "некогда тратить время — надо код писать" не поможет никакая идеальная система
Здравствуйте, AndrewVK, Вы писали:
AVK>Именно в отдельном окошке? Или какие то еще приемлемые варианты есть?
Да, я бы предпочел в отдельном окошке сбоку от кода. Это удобно, когда есть широкий экран (или два широких экрана )
И вообще, я бы предпочел, чтобы документация хранилась в отдельных XML файлах, и в коде были бы самое большее ссылки на них в комментариях. Чтобы система контроля версия могла легко различить, где правки в коде, а где в документации. И чтобы не заботиться сворачиванием/разворачиванием этой документации. Конечно, в некоторых местах кода могут встречаться короткие комментарии прямо внутри методов.
N>>, в которой можно делать закладки AVK>В каком виде закладки и как их использовать?
Ну букмарки, для навигации. Пометить место, потом туда вернуться.
N>>, есть удобная навигация и которую можно редактировать прямо в режиме rich text. AVK>В смысле прямо в редакторе кода?
Нет, не в редакторе кода, а сбоку. То есть в отдельной панели, а расположит ее пользователь, как захочет.
Здравствуйте, 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>>
Здравствуйте, AndrewVK, Вы писали:
AVK> AB>Но есть одна большая проблема — документацию надо писать и поддерживать. AVK> Значит надо сделать так, чтобы на поддержание затрачивалось как можно меньше усилий, нет?
В пределе ноль? Но ты сам ниже ответил, что так не бывает.
Если же продолжить разговор про doxygen — им, как и любым инструментом, требуется овладеть. После этого основным усилием на поддержание документации будет усилие заставить себя ее поддерживать. Т.е. пока что до технических проблем самого инструментария мы и не дошли.