Комментарии 22
Пока это выглядит лишь как ещё один формат комментариев.
Причём весьма избыточный. Ума не приложу, зачем писать такой код, где на строчку реально работающих инструкций приходится по 5 строк размышлений, почему они так работают.
Тут не надо много ума, чтобы понять, что это очень удобный формат для readme всяческих библиотек и фреймворков, туториалов, гайдлайнов и тому подобного.
Это необходимо там, где к коду пишется документация. Писать документацию прямо в коде — весьма удобно. Потом на основе этих каментов генерится нормальная читабельная документация, которую могут использовать другие разработчики.
Если же ваш код никто кроме вас не использует — такой подход может показаться лишней тратой времени и сил.
Если же ваш код никто кроме вас не использует — такой подход может показаться лишней тратой времени и сил.
Ну так можно писать документацию на интерфейсы библиотеки. Но интерфейсы — это ведь обычно ну 20% кода (максимум). А зачем так писать сам код?
Если проект большой, и над ним работают больше 1-го человека, в документировании есть большой смысл. Со временем разработчики меняются, и иметь документированный код становится насущной необходимостью.
Писать понятный самодокументирующийся код является насущной необходимостью. А объяснять каждую строку абзацом текста — это хрень какая-то, а не код.
Ага, и в документации так и будет написано — see sources, tam vsyo ponyatno.
Я вроде бы выше ясно указал на необходимость писать документацию на интерфейсы. А писать документацию на реализацию — глупо. Во-первых, накладно, во-вторых, она часто меняется, в третьих — это признак того, что что-то плохо в коде. Нет, я не против пары слов типа «тут используется такой-то алгоритм» или «это необходимо сделать для избежания такого-то бага». Но вот прямо выписывать в коде целые абзацы, объясняющие каждую строку — бред.
«это необходимо сделать для избежания такого-то бага»
А это признак костыля, и это тоже означает
что что-то плохо в коде
В остальном согласен.
>А это признак костыля, и это тоже означает
Не всегда. Вот, к примеру, пишете вы реализацию какого-то общеизвестного протокола с клиентской стороны, по спецификации. А потом оказывается, что тот сервер, с которым вы будете общаться, реализует в нём что-то по-своему, причём повлиять на его разработчиков вы не в силах. Единственный вариант — написать со своей стороны workaround с комментарием, почему оно сделано так — потому что если комментарий не написать, то эта штука будет выпилена первым же коллегой с криком «что за дурак написал эту лажу в разрез со спецификацией!».
Не всегда. Вот, к примеру, пишете вы реализацию какого-то общеизвестного протокола с клиентской стороны, по спецификации. А потом оказывается, что тот сервер, с которым вы будете общаться, реализует в нём что-то по-своему, причём повлиять на его разработчиков вы не в силах. Единственный вариант — написать со своей стороны workaround с комментарием, почему оно сделано так — потому что если комментарий не написать, то эта штука будет выпилена первым же коллегой с криком «что за дурак написал эту лажу в разрез со спецификацией!».
Писать документацию прямо в коде — ппц как неудобно:
— история изменений документации смешивается с историей изменений файла. Исправили опечатку в комментарии — получили новую версию файла
— Рефакторинг усложняется, потому что вместе с кодом надо перетаскивать еще и текст.
— Нельзя добавить рисунок или файл (e-mail, например)
— Сложно организовать поиск потакой «документации», давать ссылки на нее
— Нельзя использовать расширенное форматирование (собсвенно, вот эту проблему они вроде как решили)
Единсвенное исключение, где документация посреди кода выглядит более-менее уместно — это библиотеки. Точнее, файлы, которые описывают интерфейс библиотеки.
— история изменений документации смешивается с историей изменений файла. Исправили опечатку в комментарии — получили новую версию файла
— Рефакторинг усложняется, потому что вместе с кодом надо перетаскивать еще и текст.
— Нельзя добавить рисунок или файл (e-mail, например)
— Сложно организовать поиск потакой «документации», давать ссылки на нее
— Нельзя использовать расширенное форматирование (собсвенно, вот эту проблему они вроде как решили)
Единсвенное исключение, где документация посреди кода выглядит более-менее уместно — это библиотеки. Точнее, файлы, которые описывают интерфейс библиотеки.
Писать документацию прямо в коде — весьма удобно.
А читать потом такие простыни?
Если удалить лишнюю прозу, то получится маленький, работающий, понятный кусок кода.
Имхо, это какое-то графоманство программирования.
Имхо, это какое-то графоманство программирования.
Код обычно показывает, что нужно сделать, чтобы получить результат. Однако результат, в большинстве случаев, можно получить не одним и не двумя способами. Знание для чего эта функция, может оказаться весьма и весьма полезным. Например если прочитать последнюю фразу о super, то там и будет указано для чего мы пишем «namedMethod». Все это мегаполезно, если ваш код читает большое количество разработчиков, например в опен сорс проектах.
Проблема в том что никто не хочет писать комменты, а уж в каком формате их писать это не важно. Помечать отдельно коммент либо наоборот идентифицировать код не столь важно.
А зачем столько комментариев? Код должен описывать сам себя. Код — это «чертеж» программы. Вы же на чертеже не пишете по пять строк прозы на каждую линию. К тому же, комментарии без отступа ломают отступ кода.
В Перле POD-документацию давно можно так размещать, хотя многие опускают ее все-равно в нижнюю часть фвйла.
Система ГП, которую Кнут предлагал как альтернативу «структурному программированию» 1970-х годов, несмотря на доказанную эффективность, мало распространена из-за непонимания: многие думают, что ГП — лишь система документирования или система форматирования обычных комментариев. На самом деле, программа практически без комментариев может быть ГП, равно как и многословные примечания сами по себе не создают ГП-подхода. (Википедия)
Хоть Behavior Driven Development и несколько другая вещь, все же прослеживаются параллели — написание кода (по крайней мере тестов) в форме, напоминающей человеческий язык. Это очень актуально, я думаю, в первую очередь для описания бизнес-логики, web-сервисов и т.п.
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
CoffeeScript 1.5.0 позволяет писать комментарии в формате Markdown