Есть ли программа, которая может помочь понять другую программу?

Мне нужно документировать программное обеспечение, над которым я сейчас работаю. Программное обеспечение состоит из нескольких языков программирования и сценариев, которые заставили меня задуматься. Если появятся новые разработчики и им нужно что-то исправить, они могут знать Java, но, возможно, не bash scripting. Было бы неплохо, если бы была программа, которая помогла бы понять, что

for f in "[email protected]" ; do

означает. Я думал о чем-то, что создает статическую HTML-страницу с подсветкой кода плюс синтаксисом, и если вы наведете что-нибудь (например, "за" ), появится всплывающее окно с объяснением:

for запускает цикл, который выполняет итерацию по всем значениям, которые следуют за in. В цикле вы можете получить доступ к каждому значению с помощью переменной $f. Тело цикла находится между do и done

Что-то подобное уже существует?

[EDIT] Это всего лишь пример. Вы получите другую помощь для f, in, "[email protected]", ; и do, то есть каждый элемент строки должен быть объяснен. Неизвестные элементы (например, имена команд) должны быть связаны с Google. Поэтому вы можете понять, что он делает, даже если вам не хватает деталей.

[EDIT2] Я знаю, что вы не можете написать программу, которая понимает, что делает другая программа. То, что я ищу, - это простой инструмент, который будет делать "расширенную подсветку синтаксиса" в том смысле, что он будет окрашивать выражение и давать пояснение short, что это значит (плюс, возможно, ссылка на некоторые из них -depth).

Это предназначено для тех, кто знает, как программировать, но, возможно, раньше не видел какой-то неясной конструкции. Скажем,

echo "Error" 1>&2

Каждый программист bash знает, что это значит, но разработчик Java может быть озадачен 1>&2, несмотря на то, что они могут догадаться, что echo == System.out.println. Простой "Redirects stdout to stderr" прояснит ситуацию и даст мгновенный "AHA!". что позволяет им оставаться в их нынешнем процессе мысли.

Ответ 1

Такой инструмент можно построить с помощью ANTLR, то есть разобрать код в абстрактное синтаксическое дерево, используя грамматику ANTLR для этого язык и написать генератор HTML, который создал аннотированный код.

Это звучит как полезный инструмент для изучения языка или изучения исходного кода проектов, которые вы не поддерживаете, но подходит ли он для документации?

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

Тем не менее, я бы определенно рассмотрел такой инструмент как учебное пособие.

Ответ 2

IMO было бы проще и эффективнее собирать ссылки на хорошие ссылки на язык и учебные пособия на странице Wiki.

Для всех основных языков такие источники существуют и регулярно поддерживаются. Если вы попытаетесь создать свою собственную ссылку, вам тоже нужно ее поддерживать. Достаточно справедливо, синтаксис bash не будет меняться очень часто, но другие языки развиваются быстрее, поэтому это будет бремя.

Ответ 3

Если вы думаете об этом, не так полезно иметь инструмент, который объясняет синтаксис. Разработчики могут просто использовать Google для ключевых слов, а не просматривать веб-сайт так же, как http://www.codeweblog.com/source/.

Я считаю, что хорошие комментарии будут намного полезнее, плюс есть инструменты для извлечения документации с помощью комментариев (например, HappyDoc делает это для Python).

Ответ 4

Это очень сложная вещь. Прежде всего по определению можно доказать, что программа, которая "понимает" любую программу, не существует. Однако вы все равно можете использовать существующую документацию. Возможно, вам помогут инструменты, такие как Doxygen. Вам нужно будет документировать свой код с помощью комментариев, и документация будет сгенерирована из них.

Ответ 5

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

Кроме того, синтаксис не является сложным для большинства распространенных языков (учитывая, что код был написан с учетом удобства обслуживания).

Продолжая работу с bash, вы не можете глубоко понять bash, если вы ничего не знаете о процессах и управлении заданиями, переменных окружения, большом списке команд unix (tr, sort, cut, paste, sed, awk, find,...) и многие другие функции, которые не отображаются в синтаксисе.

Ответ 6

Если инструмент создан

для запуска цикла, который повторяется все значения, которые следуют. loop, вы можете получить доступ к каждому значению через переменная $f. Тело петли между do и done

это было бы бесполезно. Это именно тот комментарий, который программистам-стажерам (людям) говорят не писать.