CoffeeScript 1.5.0 позволяет писать комментарии в формате Markdown

    Сегодня, 25 февраля, вышла версия 1.5.0 языка CoffeeScript. В ней впервые появилась базовая поддержка так называемого «грамотного» или «литературного» программирования (literate programming). Концепцию грамотного программирования придумал Дональд Кнут в 1981 году при разработке системы TeX. В отличие от исходного кода на обычном языке программирования, который включает в себя небольшие вкрапления комментариев, грамотное программирование подразумевает написание текстового документа на естественном языке с вкраплениями кода. Многие существующие системы грамотного программирования вообще не зависят от конкретного машинного языка.

    Технически, грамотное программирование — система макросов, которая позволяет создать поверх фрагментов кода на любом языке программирования слой абстракций в виде фраз естественного языка, фактически создавая исполняемый псевдокод. Исходный файл одновременно является и исполняемой программой и документом на естественном языке, описывающем её.

    Строго говоря, в CoffeeScript 1.5.0 пока не реализована полностью концепция Дональда Кнута — раскрытие макросов не поддерживается, компилятор лишь позволяет совмещать в одном файле с расширением .litcoffee разметку Markdown и код CoffeeScript. Такой файл можно выполнять, как обычный скрипт, а можно открыть в текстовом редакторе, где он будет выглядеть как отформатированный текст с фрагментами кода. Вот скриншот скрипта написанного в новом стиле:



    А вот так он выглядит на Гитхабе в виде документа Markdown.

    Схему подсветки синтакиса .litcoffee для TextMate и SublimeText можно скачать здесь.

    Раньше похожий функционал предоставляла библиотека Docco, автором которой, как и самого языка CoffeeScript, является Джереми Ашкеназ. Она позволяет использовать в комментариях разметку Markdown и выводит текст в виде двух колонок — отформатированных комментариев и чистого исходного кода.

    Поделиться публикацией

    Комментарии 22

      +4
      Пока это выглядит лишь как ещё один формат комментариев.
        +1
        Причём весьма избыточный. Ума не приложу, зачем писать такой код, где на строчку реально работающих инструкций приходится по 5 строк размышлений, почему они так работают.
          +10
          Тут не надо много ума, чтобы понять, что это очень удобный формат для readme всяческих библиотек и фреймворков, туториалов, гайдлайнов и тому подобного.
            +8
            Это необходимо там, где к коду пишется документация. Писать документацию прямо в коде — весьма удобно. Потом на основе этих каментов генерится нормальная читабельная документация, которую могут использовать другие разработчики.

            Если же ваш код никто кроме вас не использует — такой подход может показаться лишней тратой времени и сил.
              +2
              Ну так можно писать документацию на интерфейсы библиотеки. Но интерфейсы — это ведь обычно ну 20% кода (максимум). А зачем так писать сам код?
                0
                Если проект большой, и над ним работают больше 1-го человека, в документировании есть большой смысл. Со временем разработчики меняются, и иметь документированный код становится насущной необходимостью.
                  +3
                  Писать понятный самодокументирующийся код является насущной необходимостью. А объяснять каждую строку абзацом текста — это хрень какая-то, а не код.
                    +2
                    Ага, и в документации так и будет написано — see sources, tam vsyo ponyatno.
                      +1
                      Я вроде бы выше ясно указал на необходимость писать документацию на интерфейсы. А писать документацию на реализацию — глупо. Во-первых, накладно, во-вторых, она часто меняется, в третьих — это признак того, что что-то плохо в коде. Нет, я не против пары слов типа «тут используется такой-то алгоритм» или «это необходимо сделать для избежания такого-то бага». Но вот прямо выписывать в коде целые абзацы, объясняющие каждую строку — бред.
                        0
                        «это необходимо сделать для избежания такого-то бага»

                        А это признак костыля, и это тоже означает
                        что что-то плохо в коде

                        В остальном согласен.
                          0
                          >А это признак костыля, и это тоже означает

                          Не всегда. Вот, к примеру, пишете вы реализацию какого-то общеизвестного протокола с клиентской стороны, по спецификации. А потом оказывается, что тот сервер, с которым вы будете общаться, реализует в нём что-то по-своему, причём повлиять на его разработчиков вы не в силах. Единственный вариант — написать со своей стороны workaround с комментарием, почему оно сделано так — потому что если комментарий не написать, то эта штука будет выпилена первым же коллегой с криком «что за дурак написал эту лажу в разрез со спецификацией!».

                            0
                            Это называется «костыль» :)
                              0
                              Это называется «нужный костыль» :)
                0
                Писать документацию прямо в коде — ппц как неудобно:
                — история изменений документации смешивается с историей изменений файла. Исправили опечатку в комментарии — получили новую версию файла
                — Рефакторинг усложняется, потому что вместе с кодом надо перетаскивать еще и текст.
                — Нельзя добавить рисунок или файл (e-mail, например)
                — Сложно организовать поиск потакой «документации», давать ссылки на нее
                — Нельзя использовать расширенное форматирование (собсвенно, вот эту проблему они вроде как решили)

                Единсвенное исключение, где документация посреди кода выглядит более-менее уместно — это библиотеки. Точнее, файлы, которые описывают интерфейс библиотеки.
                  0
                  Писать документацию прямо в коде — весьма удобно.

                  А читать потом такие простыни?
              +11
              Если удалить лишнюю прозу, то получится маленький, работающий, понятный кусок кода.

              Имхо, это какое-то графоманство программирования.
                0
                Код обычно показывает, что нужно сделать, чтобы получить результат. Однако результат, в большинстве случаев, можно получить не одним и не двумя способами. Знание для чего эта функция, может оказаться весьма и весьма полезным. Например если прочитать последнюю фразу о super, то там и будет указано для чего мы пишем «namedMethod». Все это мегаполезно, если ваш код читает большое количество разработчиков, например в опен сорс проектах.
                +16
                Что бы не делать, лишь бы не source map'ы.
                  +1
                  Проблема в том что никто не хочет писать комменты, а уж в каком формате их писать это не важно. Помечать отдельно коммент либо наоборот идентифицировать код не столь важно.
                    +1
                    А зачем столько комментариев? Код должен описывать сам себя. Код — это «чертеж» программы. Вы же на чертеже не пишете по пять строк прозы на каждую линию. К тому же, комментарии без отступа ломают отступ кода.
                      +1
                      В Перле POD-документацию давно можно так размещать, хотя многие опускают ее все-равно в нижнюю часть фвйла.
                        +1
                        Система ГП, которую Кнут предлагал как альтернативу «структурному программированию» 1970-х годов, несмотря на доказанную эффективность, мало распространена из-за непонимания: многие думают, что ГП — лишь система документирования или система форматирования обычных комментариев. На самом деле, программа практически без комментариев может быть ГП, равно как и многословные примечания сами по себе не создают ГП-подхода. (Википедия)


                        Хоть Behavior Driven Development и несколько другая вещь, все же прослеживаются параллели — написание кода (по крайней мере тестов) в форме, напоминающей человеческий язык. Это очень актуально, я думаю, в первую очередь для описания бизнес-логики, web-сервисов и т.п.

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

                        Самое читаемое