AndreTMНарод, вы много видели документированного кода?
Вообще, чем выше класс программиста - тем меньше приходится документировать код. Ибо... и ИМХО.
Я все же повторю вопрос.
Имеется ввиду руководство, описывающиее назначение системы, обоснование выбранных архитектурных решений и т.д.? Или же документация по функциям АПИ/фреймворка?

авторНарод, вы много видели документированного кода?
Много

автор
Вообще, чем выше класс программиста - тем меньше приходится документировать код. Ибо... и ИМХО.
Всю жизнь думал, что документация по фреймворку - это такой же необходимый документальный артефакт, как и вышеупоминаемые вами документы.

Иначе, накой в документации тех же фреймворков и АПИ Микрософт присутсвует документация по сотням вполне интуитивно понятных функций? Уровень их команды низкий?


softwarerEdd.Dragonэто описание-шапка функции, необходимое для автоматического формирования документации по классу, модулю и т.д. Это бред?
Автоматическое формирование документации - это бред. Как раз одна из тех вещей, которые не относятся к комментариям по делу.
Т.е. описание параметров методов, по сути хелп, не нужен в коде и его надо писать исключительно отдельно от кода, беря на себя все форматирование и т.д.? А IDE потом в подсказки должна будет выводить хелп из этой внешней документации?

Edd.Dragon
авторНарод, вы много видели документированного кода?
Много

Любой толковый фрейморвк, АПИ или просто набор заголовочных файлов к бибилиотеке не зависимо от языка.

Безумный DBA

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

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

И человек, который не может доходчиво описать свою мысль в коде - вряд-ли ее опишет хорошо на естественном языке.

Ценность же этих комментариев - разве для совсем начинающих, которые даже программировать еще не умеют (в принципе).
Елки двадцать!

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

Безумный DBA
Абсолютно всю документацию следует описывать в отдельных документах.
Описывать ее в коде (идея JavaDoc) примерно настолько-же идиотичная затея, как и прикладывать
к свежевыпущенному автомобилю, во всех пикантных местах (в трубах рамы, под сиденями, в коробке передач, в шиназз) - документацию (чертежи и расчеты).
Это ведь так удобно, да?
Смешно?

Вообще-то печально.

Ибо автомобиль - это экзешник, а не код. А код - это такой же ДОКУМЕНТ как и ТЗ, и чертежи, и мануалы. Только мануалы преследуют одну цель - научить, а код - другую - реализовать (точнее описать процесс реализации). Код - это документ, по которому ты автомобиль создаешь. И в этом документе наличие поясняющих бирок как раз ни разу не идиотизм. Это всего-лишь интеграция документации (в разумных размерах) и кода для более эффективного пользования им в дальнейшем.

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


Безумный DBA
Решил поремонтировать двигатель, открываешь коробку - а там чертеж уже лежит и техкарта, для изготовления нового цилиндра из отливки.

Смешно?

Открываешь пакет с чертежом и инструкцией по изготовлению по этому чертежу. Одно из них мануал, другое - код. Удобно, что они лежат вместе? Удобно. Это мешает иметь еще и автоматически ксерящийся по ним набор просто инструкций или просто чертежей, если такой набор понадобится? Не мешает.

Безумный DBA
Описывать ее в коде (идея JavaDoc) примерно настолько-же идиотичная затея, как и прикладывать

Эта идея возникла еще когда Явы и в помине не было.
Идея JavaDoc состоит лишь в стандартизации таких коментариев для генерации из них симпатишной html-документации, но не в их необходимости.

авторЕсть сомнения? Ну так посмотрите лишний раз на документацию в MSDN, и сравните ее с тем, извиняюсь, нечитабельным нечтом, которое генерируется через javadoc даже в самой в JDK.
Есть сомнения.
Ибо наличие MSDN никак не устраняет необходимости иметь сокращенные описания и подсказки по функциям и их параметрам. Где-то они должны храниться. Так какой смысл их хранить в отдельных файлах, если они таки лаконичные и могут прекрасно дополнять сам код, не мешая его читать, т.к. находятся между логическими блоками, между функциями?

Безумный DBA
Если до сих пор не понятно, поясним. Для кого пишутся эти комментарии в коде? Зачем они там?
Кто их будет там читать?

Для тех, кто пользуется этим кодом!
Что ты читаешь во всплывающих подсказках в Студии в выбадающем по Ctrl+Space списке функций? MSDN или краткие описания? Т.е. они есть, их не может не быть в нормальной среде разработки. А вопрос в том, где их хранить: в отдельной XML-ине или в исходнике. Оба варианта имеют право на жизнь. И второй вариант не является каким-то ущербным, не мешает читать код и дает необходимую, дополнительную к именам этих функций и их параметров, информацию прямо на месте, что удобно например при рефакторинге. Если кому это неудобно, так на здоровье! Но коменты то эти нужны и писать их, и править нужно. Вот только получается в отдельном файле, в котором нужно повторить объявление функции и приписать ее описание.

Убедить в том, что один вариант правильный, а другой нет - врядли получится. Кому как нравится, и у кого какая среда что поддерживает. А вот полное их отсутствие, имхо, глупо. Т.к. по большинству функций развернутое бла-бла-бла, достойное статьи в MSDN не нужно, а сами идентификаторы не всегда передают суть полноценно и к объявлению нужно добавить пару уточнений, которые и хочется видеть при выборе функций или при их правке.


Безумный DBA
Вообще ничего не понял. А чем названия классов и переменных - не бирки?

" а сами идентификаторы не всегда передают суть полноценно и к объявлению нужно добавить пару уточнений, которые и хочется видеть при выборе функций или при их правке. "


Безумный DBA
Вовсе нет. Не дистрибутив. Сам код - это уже конечный продукт. Никто уже (из людей, кроме кодеров, которые, по сути, эдакие биороботы по переработке спецификаций в строки кода) не
работает с ним.

Конечный продукт - это как раз то, с чем работает потребитель этого продукта. И конечный пользователь, и тестер работают (как ты и говоришь противореча сам себе), грубо говоря, с exe-шником. Пользователь им пользуется. Тестер его тестирует. При этом тестер вооружается инструкцией, спецификацией или иными доками. Но он же не доки тестирует, а продукт (exe-шник, web-сервис и т.д.).

А код - это алгоритм сборки продукта - документ, понятный производственной линии (компилятору), которая связывает указанные в алгоритме узлы указанным образом. Отличия от реального производства только в том, что продукт в целом, узлы (являющиеся более мелкими продуктами) - все виртуальное. Т.е. в реальности еще и материалы нужны, а тут не нужны. Любая деталь этого виртуального продукта в свою очередь является таким же виртуальным продуктом, только что или ранее аналогичным образом собранная компилятором.

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


Безумный DBA
Мда. Вообще плохо, конечно, кто кодеров не учат базовым инженерным дисциплинам.
ЕСКД, ЕСТД + правилам написания пояснительных записок.
Все беды кодеров, как я понимаю, от неокрепших на простейших метафорах и аналогиях мозгов.
Все беды *не знаю, кем вы себя величаете* в том, что вполне ясное название "Единая система конструкторской документации" загадочным образом трансформируется в "Единственно истинная система документации в любых (или в моих, а других не бывает) проектах". При чем пусть даже и истинная, но при этом не терпящая дополнения другими, кому-то удобными и полезными артефактами и подходами. Мол, черное, даже если вы в него нальете белого, обязано остаться черным! Как хотите! И плевать, что оно, чисто черное, тут не вовсем к месту.

Безумный DBAAndreTMТак что комментирование кода, и комментирование функционала - абсолютно разные функции. А нас заставляют делать первое, и не учат делать второе...

Ура! Кое-кто начал кое-что подозревать.
Я начал подозревать, что мы говорим о разных вещах.