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

[bubuq]

Пока это выглядит лишь как ещё один формат комментариев.

[tangro]

Причём весьма избыточный. Ума не приложу, зачем писать такой код, где на строчку реально работающих инструкций приходится по 5 строк размышлений, почему они так работают.

[neoromantic]

Тут не надо много ума, чтобы понять, что это очень удобный формат для readme всяческих библиотек и фреймворков, туториалов, гайдлайнов и тому подобного.

[IntenT]

Это необходимо там, где к коду пишется документация. Писать документацию прямо в коде — весьма удобно. Потом на основе этих каментов генерится нормальная читабельная документация, которую могут использовать другие разработчики.

Если же ваш код никто кроме вас не использует — такой подход может показаться лишней тратой времени и сил.

[tangro]

Ну так можно писать документацию на интерфейсы библиотеки. Но интерфейсы — это ведь обычно ну 20% кода (максимум). А зачем так писать сам код?

[IntenT]

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

[tangro]

Писать понятный самодокументирующийся код является насущной необходимостью. А объяснять каждую строку абзацом текста — это хрень какая-то, а не код.

[IntenT]

Ага, и в документации так и будет написано — see sources, tam vsyo ponyatno.

[tangro]

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

[4ika]

«это необходимо сделать для избежания такого-то бага»

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

что что-то плохо в коде

В остальном согласен.

[tangro]

>А это признак костыля, и это тоже означает

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

[linuxoid]

Это называется «костыль» :)

[tangro]

Это называется «нужный костыль» :)

[beardog]

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

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

[GrigoryPerepechko]

Писать документацию прямо в коде — весьма удобно.

А читать потом такие простыни?

[TheShock]

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

Имхо, это какое-то графоманство программирования.

[feligz]

Код обычно показывает, что нужно сделать, чтобы получить результат. Однако результат, в большинстве случаев, можно получить не одним и не двумя способами. Знание для чего эта функция, может оказаться весьма и весьма полезным. Например если прочитать последнюю фразу о super, то там и будет указано для чего мы пишем «namedMethod». Все это мегаполезно, если ваш код читает большое количество разработчиков, например в опен сорс проектах.

[enDal]

Что бы не делать, лишь бы не source map'ы.

[prudis]

Проблема в том что никто не хочет писать комменты, а уж в каком формате их писать это не важно. Помечать отдельно коммент либо наоборот идентифицировать код не столь важно.

[Triang3l]

А зачем столько комментариев? Код должен описывать сам себя. Код — это «чертеж» программы. Вы же на чертеже не пишете по пять строк прозы на каждую линию. К тому же, комментарии без отступа ломают отступ кода.

[Foxcool]

В Перле POD-документацию давно можно так размещать, хотя многие опускают ее все-равно в нижнюю часть фвйла.

[scrivener]

Система ГП, которую Кнут предлагал как альтернативу «структурному программированию» 1970-х годов, несмотря на доказанную эффективность, мало распространена из-за непонимания: многие думают, что ГП — лишь система документирования или система форматирования обычных комментариев. На самом деле, программа практически без комментариев может быть ГП, равно как и многословные примечания сами по себе не создают ГП-подхода. (Википедия)

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