Методы документирования

[Svatov]

Возникла необходимость в функионале IDE для более удобного документирование и навигации по документу.

Описываю пример, и чего ожидаю я.

Есть допустим очень большой CSS файл > 20000 строк, нужны удобные средства документирование, что именно:

1. Создать якорь с названием, по которому я смогу быстро перемещаться в необходимую часть документа.

2. Желательно нумерацию (а еще желательней переменные), изменив допустим порядок или номер чтобы калькулировались другие на соотвествующие.

Ну, а также возможно поддержка этого всего на уровне IDE с тултипами и пояснениями подхватывающее с этих комментов.

SASS LESS...как бы помогают, но всеравно не решают проблему.

(знаком с JSDoc, DocBlock, Tasks в Eclipse)

Больше всего нуждаюсь в пункте 1.

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

[Softlink]

1. Создать якорь с названием, по которому я смогу быстро перемещаться в необходимую часть документа.

Я уже плотно пересел на Sublime, так вот что похожего есть в нем.

1.1 Стандартные закладки Ctrl+F2(создать закладку) и F2(встать на нее). Перебирает он все закладки по очереди.

1.2 Goto. Работает почти хорошо. Но не ищет в комментариях. А в целом алгоритм таков.

Пишем код и, например, запоминаем строку(название закладки ведь тоже запоминать надо ). Далее Ctrl+P > index.html:512, где index.html - имя файла в котором надо найти, и 512 - строка.

Можно искать по символу index.html@b_class. Ищет моментально.

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

Тоже интересовался этим вопросом ранее, но плагинов каких-то не нашел к нему. Про другие редакторы я не знаю

[lexxcode]

Ну так в том же ST2 когда ищешь по селекторам через @ выводится полный список того, что есть в файле css, и если не помнишь название, можно пролистать список и найти, то что нужно. Даже не знаю, что еще можно желать)

[Softlink]

Ну так в том же ST2 когда ищешь по селекторам через @ выводится полный список того, что есть в файле css, и если не помнишь название, можно пролистать список и найти, то что нужно. Даже не знаю, что еще можно желать)

Это тоже, да. Я понимаю ТС надо, да и вообще, неплохо бы было иметь именованные закладки и искать по ним.

[lexxcode]

И, что для каждого нового файла создавать новый пак закладок??

[gift]

Мне кажется, документировать такой объём кода — это дорога в никуда.

Стоит начать с того, откуда у вас такой огромный CSS? Поддерживать вменяемого его нереально, энтропии с каждым изменением вс больше и больше.

Если он компилируется откуда-то (с помощью БЭМ-утилит, например), то вопроса бы не возникло: всё лежит аккуратно по своим каталогам, объём кода вполне осознаваемый в одиночку. А если не компилируется, а написан руками, то стоит задуматься, почему бы его не рефакторить до чего-то вменяемого?

[Svatov]

Мне кажется, документировать такой объём кода — это дорога в никуда.

Стоит начать с того, откуда у вас такой огромный CSS? Поддерживать вменяемого его нереально, энтропии с каждым изменением вс больше и больше.

Если он компилируется откуда-то (с помощью БЭМ-утилит, например), то вопроса бы не возникло: всё лежит аккуратно по своим каталогам, объём кода вполне осознаваемый в одиночку. А если не компилируется, а написан руками, то стоит задуматься, почему бы его не рефакторить до чего-то вменяемого?

Когда кажется креститься нужно, а по существу?

[gift]

Это более чем по существу. Помните, как у Кернигана и Пайка, если не изменяет память: «хороший код не надо комментировать, он осмысленный сам по себе». Это, конечно, про Си, но тем не менее. Точно оттуда же: «в один из своих самых продуктивных дней я удалил больше 1000 строк кода». Не наводит на размышления?

CSS длиной больше 20 тысяч строк, написанный вручную, это скорее приговор, чем необходимость что-то комментировать. Попробуйте его уменьшить, разбить на модули — словом, провести рефакторинг. Тогда и никаких мудрёных схем документирования выдумывать не придётся.

[Svatov]

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

[gift]

Кода длиной в 20 тысяч строк у меня и впрямь не было, и слава богу!

Но уж насчёт «пробуете» — увольте! Под 100 сайтов сверстал на фрилансе, спроектировал, нарисовал и сверстал интерфейсы 2 крупных и одной маленькой систем, делал кое-что в организациях, прочёл кучу литературы про разработку ПО (не только вёрстку), программировал на Си, С++, Perl, PHP... Достаточный послужной список?

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

[Svatov]

Нельзя, он под копирайтом IBM. Мне вашего взгляда со стороны было уже достаточно, спасибо.

[gift]

Проще надо быть, и люди к вам потянутся.

Вопрос документирования как-то решился? Любопытно ведь!

[s0rr0w]

Для решения сложных задач, порой требуются простые вещи.

В коде создаем комментарии вида

<!-- ///foo1 -->
<!-- ///foo2 -->
...

И поиск делаем так: Ctrl+F ///foo1 Enter

[Vin]

Для решения сложных задач, порой требуются простые вещи.

В коде создаем комментарии вида

<!-- ///foo1 -->

<!-- ///foo2 -->

...

И поиск делаем так: Ctrl+F ///foo1 Enter

Я примерно так и делаю, хотя сам ещё никогда не работал с единым CSS-файлом объёмом аж 20 000 строк или близким к этому

[Svatov]

Для решения сложных задач, порой требуются простые вещи.

В коде создаем комментарии вида

<!-- ///foo1 -->
<!-- ///foo2 -->
...

И поиск делаем так: Ctrl+F ///foo1 Enter

Действительно это один из очевидных методов, в данный момент я его и использую, создаю в начале документа Table of Contents, чтобы легко ориентироваться в структуре и разделяю основные разделы именно таким способом.