Здравствуйте, Unmanaged, Вы писали:
U>>>специфика — Windows Kernel и GUI RO>>Это как?
U>>>Разумеется, у меня есть эталон стиля кода — это стиль исходного кода ядра Windows. RO>>А откуда программер может быть с ним знаком? :-O
U>>>И конечно, я смотрю, чтобы бы стиль кода кандидата был не хуже моего. RO>>Как один стиль может быть «хуже» другого?
U>Довольно глупые вопросы. U>Извините, я не знаю как на них отвечать.
U>P.S. U>Вот после таких и подобных им вопросов лично я обычно прощаюсь с соискателем.
С годами все больше убеждаюсь, что самый лучший критерий отбора, поработать вместе 1 месяц.
ЗЫ: Ну ответь мне какой стиль расстановки лучше(читабельнее), когда скобочка на этой же строке(JAVA стиль его называют) и когда на новой строке? Если ты ответишь что какой то лучше а другой хуже, я бы тебя тоже на работу не взял . Потому что тебе трубно будет работать с чужим кодом. Я тоже приверженец своего стиля, но я его не навязываю другим. Вообще такой подход к отбору кандидатов, смахивает на собеседование с HR, а не с программистом. Вот когда чел пишет совсем без стиля(а такие кстати есть), т.е. пишет буковки как придется, тогда согласен, с ним трудно писать код, а тем более его саппортить.
Здравствуйте, landerhigh, Вы писали:
Pzz>>Они (комменты), наверное еще и апдейтятся автоматически? Т.е., поменял поведение функции, глядь, комменты сами и изменились? Или, может быть, современные компиляторы научились хотя бы выдавать предупреждение о несоответствии того, что написано в комменте и того, что написано в коде? L>Проекту doxygen уже 10 лет как стукнуло. Если, к примеру, параметры функции названы правильно, а не имеют вид вроде Param1, и само имя функции отображает ее назначение, то генерируется вполне читаемая документация. С типами аргументов и возвращаемого значения. За исключением вырожденных случаев вроде функций в 500 строк, в которых все равно без поллитры не разберешься.
И что, доксиген сам проверяет соответствие комментария и кода функции?
На мой взгляд, доксигеновская документация годится только на то, чтобы показывать большому начальству со словами, вот у нас документация тоже есть. Потому что reference по функциям или по методам без объяснения картины в целом нифига не помогает чего-либо понять.
Здравствуйте, Pzz, Вы писали:
Pzz>Хуже всего сделать что-то интересненькое, и получить судебное разбирательство на тему, что идея/код украдены из нелегально увиденных исходников. Если человек всюду звенит, что он эти исходники читал, наверное и на суде это всплывет. Нафиг-нафиг. Меньше знаешь — лучше спишь
Здравствуйте, Pzz, Вы писали:
L>>Проекту doxygen уже 10 лет как стукнуло. Если, к примеру, параметры функции названы правильно, а не имеют вид вроде Param1, и само имя функции отображает ее назначение, то генерируется вполне читаемая документация. С типами аргументов и возвращаемого значения. За исключением вырожденных случаев вроде функций в 500 строк, в которых все равно без поллитры не разберешься. Pzz>И что, доксиген сам проверяет соответствие комментария и кода функции?
См выделенное. Некоторые еще это называют "самодокументируемый код" Pzz>На мой взгляд, доксигеновская документация годится только на то, чтобы показывать большому начальству со словами, вот у нас документация тоже есть. Потому что reference по функциям или по методам без объяснения картины в целом нифига не помогает чего-либо понять.
Молотком тоже можно все пальцы отбить себе..
Здравствуйте, landerhigh, Вы писали:
L>Здравствуйте, Pzz, Вы писали:
Pzz>>И что, доксиген сам проверяет соответствие комментария и кода функции? L>См выделенное. Некоторые еще это называют "самодокументируемый код"
Блин, если имя функции и параметров отражает их назначение, то документация, казалось бы, вообще не нужна?
Докумантация на функцию должна в первую очередь быть спецификацией ее семантики. Уж типы параметров и т.п. можно как-нибудь угадать из прототипа функции.
Pzz>>На мой взгляд, доксигеновская документация годится только на то, чтобы показывать большому начальству со словами, вот у нас документация тоже есть. Потому что reference по функциям или по методам без объяснения картины в целом нифига не помогает чего-либо понять. L>Молотком тоже можно все пальцы отбить себе..
Можно. Но молотком очень трудно заводить наручные часы.
Здравствуйте, Pzz, Вы писали:
Pzz>>>На мой взгляд, доксигеновская документация годится только на то, чтобы показывать большому начальству со словами, вот у нас документация тоже есть. Потому что reference по функциям или по методам без объяснения картины в целом нифига не помогает чего-либо понять. L>>Молотком тоже можно все пальцы отбить себе..
Pzz>Можно. Но молотком очень трудно заводить наручные часы.
Мы немного корячили доксиджен и с помощью напильника получали довольно сносный формат документации. Правда врядли кто то из разработчиков решится это повторить...
Здравствуйте, NikeByNike, Вы писали:
NBN>Мы немного корячили доксиджен и с помощью напильника получали довольно сносный формат документации. Правда врядли кто то из разработчиков решится это повторить...
Мой point заключается в том, что писание документации — это такая же вдумчивая работа, как писание кода. Никакая автоматически сгенеренная документация не заменяет нормальной документации, написанной живым человеком специально для этой цели, а не в качестве побочного продукта при кодировании. Да, я понимаю, нету времени, нету людей, дедлайн прошел месяц назад, что очень лень и все такое. Но если, ребята, у вас нет времени написать документацию, то у вас и не будет документации, не надо себя обманывать.
Единственное оправдание держать документацию в исходниках, это пресловутая возможность пройтись по ним доксигеном. Потому что вообще-то в исходниках развесистые комментарии только мешают, затеняя логику самого кода. А так как от доксигеновской документации все равно, см. выше, проку мало, то и незачем ради нее исходники марать.
Назначение комментариев в исходниках — быть именно пояснением к исходникам, а не заменой документации. Именно из этого и следует исходить, выбирая стиль, в котором пишутся комментарии.
Ковырянием же доксигена можно, наверное, повлиять на стиль, в котором он форматирует свой output. Но я говорю совсем не об этом.
Здравствуйте, Pzz, Вы писали:
Pzz>>>И что, доксиген сам проверяет соответствие комментария и кода функции? L>>См выделенное. Некоторые еще это называют "самодокументируемый код" Pzz>Блин, если имя функции и параметров отражает их назначение, то документация, казалось бы, вообще не нужна? Pzz>Докумантация на функцию должна в первую очередь быть спецификацией ее семантики. Уж типы параметров и т.п. можно как-нибудь угадать из прототипа функции.
Не поверите, но это именно то, что доксиджен и делает. Если же девелопер имеют практику перед декларацией функции написать, что это за зверь, с чем его едят и побочные эффекты поедания, то получается то, что можно назвать essential documentation.
Здравствуйте, landerhigh, Вы писали:
L>Здравствуйте, Pzz, Вы писали:
Pzz>>Блин, если имя функции и параметров отражает их назначение, то документация, казалось бы, вообще не нужна? Pzz>>Докумантация на функцию должна в первую очередь быть спецификацией ее семантики. Уж типы параметров и т.п. можно как-нибудь угадать из прототипа функции. L>Не поверите, но это именно то, что доксиджен и делает. Если же девелопер имеют практику перед декларацией функции написать, что это за зверь, с чем его едят и побочные эффекты поедания, то получается то, что можно назвать essential documentation.
Доксиген делает не это. Все, что делает доксиген, это незамысловатые манипуляции над текстом. Если чепуха на входе, чепуха будет и на выходе.
Я свою позицию уже один раз изложил, не вижу смысла повторяться при отсутствии новых контраргументов:
Здравствуйте, Pzz, Вы писали:
L>>Не поверите, но это именно то, что доксиджен и делает. Если же девелопер имеют практику перед декларацией функции написать, что это за зверь, с чем его едят и побочные эффекты поедания, то получается то, что можно назвать essential documentation. Pzz>Доксиген делает не это. Все, что делает доксиген, это незамысловатые манипуляции над текстом. Если чепуха на входе, чепуха будет и на выходе.
Если чепуха на входе, то чепуха и в коде. Тут не о чем разговаривать, надо гнать в шею аффтара чепухи. Pzz>Я свою позицию уже один раз изложил, не вижу смысла повторяться при отсутствии новых контраргументов: Pzz>http://www.rsdn.ru/forum/message/2749594.1.aspx
Уже привели единственный достаточный аргумент — после первого же коммита/багфикса/рефакторинга отдельная вдумчиво написанная документация становится бесполезной, а время, на нее потраченное — выкинутым впустую.
Да, речь идет о документации кода, а не архитектуры.
Никто не вылизывал этот код для юзеров (вот еще, ресурсы тратить ). Это реальный код из реального build tree операционной системы.
Шелл у нас мдааа... но, говоря про "хороший стиль кодирования виндов" — говорят именно о кернеле и вообще о native OS. Шелл писала другая команда, команда Win95, и написан он именно такими же руками, что и вся Win95.
Pzz>Хуже всего сделать что-то интересненькое, и получить судебное разбирательство на тему, что идея/код украдены из нелегально увиденных исходников. Если человек всюду звенит, что он эти исходники читал, наверное и на суде это всплывет. Нафиг-нафиг. Меньше знаешь — лучше спишь
Если "интересненькое" сделано под винды, не в конкуренцию одному из продуктов Microsoft, и, таким образом, ворованный код использовался только для того, чтобы лучше понимать, как работает платформа у тебя под ногами — то расслабьтесь. Никто на вас в суд подавать не будет, как не подают в суд на тех, кто сделал reverse engineering каких-то кусков ядра виндов и опубликовал результаты.
Pzz>Если нет, то что за радость от того, что они механически чекинятся одновременно с функцией?
Не запускать отдельные тулы для чтения документации. Это раз. Документация обязательно видна и мозолит глаза при работе с кодом, это два.
А что за радость в отдельной документации вне комментов?
MSS>>Если параметров просто много — то есть смысл, чтобы четче понимать, где какой параметр. Pzz>Если параметров просто много, значит функция просто продумана плохо.
Придумайте CreateFile с меньшим числом параметров, учитывая весьма развитый функционал этой функции, намного богаче, чем в юниксных аналогах.
Pzz>Примерчики из DDK просто ужасны. Не в смысле стиля расставления скобочек, а в смысле архитектуры программы. В них любое действие, которое логически состоит из нескольких последовательных шагов, размазано тонким слоем по всему примерчику.
Конкретику можно? какое именно действие, какие шаги, как размазано.
Есть такое подозрение, что после приведения вами примеров станет ясно, что причина этого не в стиле кодирования DDK, а в архитектуре ядра NT.
Pzz>Тех, кто учился программировать по DDK, надо долго и мучительно переучивать.
Смотря что разработчикам предстоит разрабатывать. Если что угодно в ядре виндов — то не нужно переучивать, DDK есть истина в последней инстанции.
Причина делать такое утверждение очень проста: программируют, в частности, под платформу. Я понимаю, что программируют еще и под требования, и под соображения о красоте программирования — но если платформа достаточно сложна, то соображения "правильно воткнуться в платформу" уж точно перевешивают ЛЮБЫЕ (еще раз all caps — ЛЮБЫЕ) соображения красоты кода из любой литературы.
Ядро НТ — достаточно сложная платформа с кучей тонких нюансов, которые могут породить кучу неприятных сложных в поиске багов именно в месте стыка "ваш код-платформа". Потому именно это место стыка начинает становиться _главным_ в вашем коде, а вовсе не его внутренняя красота.
М>Вы всерьез считаете, что в MS именно кодер пишет спецификацию? М>По моим недалеким представлениям, с этой шапки (уже для него готовой!) он начинает работать...
В каком-нить сраном .NET (я не про MSCOREE.DLL, а про классы фреймворка) или там SharePoint это, возможно, так и есть, но в ядре, я вас уверяю, дело обстоит совсем иначе.
Исторически ядро было написано группой единомышленников человек в 30-40 (это если считать авторов драйверов под главнейшее железо и авторов основных кернел-модулей типа NTFS, NDIS, SMB клиента и сервера и тому подобного).
Люди давно работали вместе еще в Digital, хорошо сработаны, и при возникновении тех или иных вопросов просто спрашивали друг друга лично.
Понятно, что в этой среде просто не нужны тупые кодеры, а если кодер умный — то почему бы ему и не дать писать свою спецификацию?
Полной внутренней документации на ядро никогда не существовало. Документация в MSDN сделана отдельной командой (DDK support Элиаса Якуба), не имеющей прямого отношения к девелопменту ядра. Сделана эта документация на основе как существующего кода, так и личных бесед с code owners каждого модуля. Багов в ней было — до кучи. Конкурсы объявляли на нахождение лучшего бага.
Сейчас, по сплетням, пишут оную документацию, чтобы удовлетворить судью в иске Еврокомиссии.
P.S. В список подсистем не вошел TCP/IP, и к тому есть причины. Его перетащили за уши из OS/2 LAN Manager 1.x, он даже в другом стиле кодирования написан, чем все остальное ядро, и не переделывался аж до Висты (в Висте как минимум поменяли интерфейсы верхнего края — был TDI transport, стал WSK provider).
Pzz>Мой point заключается в том, что писание документации — это такая же вдумчивая работа, как писание кода.
На деле она нужна практически только при раздаче кода _без исходников_, бинарями, внешним людям. Т.е. она нужна только авторам фреймворков, тулкитов и платформ. Причем фреймворков и тулкитов, раздаваемых наружу без исходников.
Второе, зачем нужна документация — краткое описание общей архитектуры продукта, базовых принципов, обязательных к соблюдению (скажем, инвариантов базового класса, которые обязаны остаться инвариантами в потомках), и так далее.
Любая другая документация в виде отдельных файлов просто не нужна. Например, ее не будут читать, да и разъедется она с кодом намного быстрее, чем комментарии в коде.
Доксиджен — не нужен. Смысл пережевывать комментарии парсером, чтобы сгенерить из них отдельный от кода файл, скажем, HTML? почему человек не может читать прямо из кода? зачем эта промежуточная обработка?
Pzz>очень лень и все такое. Но если, ребята, у вас нет времени написать документацию, то у вас и не будет документации, не надо себя обманывать.
И не надо. Это вложение денег компанией — не окупается.
Pzz>Единственное оправдание держать документацию в исходниках, это пресловутая возможность пройтись по ним доксигеном.
Нет. Доксиджен как раз не нужен, см. выше.
Pzz> Потому что вообще-то в исходниках развесистые комментарии только мешают,
Они и есть документация. Например, вся семантика почти любой функции описывается в максимум 20 строк комментария перед ее декларацией.
Здравствуйте, Unmanaged, Вы писали:
U>Я имею в виду, что чем менее читабельно выглядят исходники программиста, тем менее качественный код он пишет.
Мне кажется, ты пытаешься поднять совсем другую проблему. Споры C vs C++ в ядре на самом деле идут уже давно, и, по аналогии с asm vs C, уже понятно, что победит завтра.
Можешь читать сорцы буста? Если нет, то позиция ясна — поэтому ты и принадлежишь к консерваторам. Вообще я считаю такие споры напрасными, очевидно, что кто-то, в силу выработанной годами привычки, способен с закрытыми глазами писать качественный код в стиле MS, зачем им тратить время и перестраиваться на неэффективный в силу субъективных факторов метод? В то же время, не вижу никаких причин прививать этот стиль выросшим на книгах Александреску и Мэйерса — читать-то они его смогут, но писать... только когда действительно без него никак.
People who are more than casually interested in computers should have at least some idea of what the underlying hardware is like. Otherwise the programs they write will be pretty weird (c) D.Knuth
Здравствуйте, Roman Odaisky, Вы писали:
RO>Каким-то чудом с использованием этого стиля была написана целая ОС… ее даже используют… новые версии выпускают.
А есть ли у них выбор, с какого года сорцы то?
People who are more than casually interested in computers should have at least some idea of what the underlying hardware is like. Otherwise the programs they write will be pretty weird (c) D.Knuth
Здравствуйте, Maxim S. Shatskih, Вы писали:
MSS>Если "интересненькое" сделано под винды, не в конкуренцию одному из продуктов Microsoft, и, таким образом, ворованный код использовался только для того, чтобы лучше понимать, как работает платформа у тебя под ногами — то расслабьтесь. Никто на вас в суд подавать не будет, как не подают в суд на тех, кто сделал reverse engineering каких-то кусков ядра виндов и опубликовал результаты.
Вы собираетесь всю жизнь писать драйвера для виндов?
"Maxim S. Shatskih" <29705@users.rsdn.ru> writes:
> Доксиджен — не нужен. Смысл пережевывать комментарии парсером, чтобы > сгенерить из них отдельный от кода файл, скажем, HTML? почему человек > не может читать прямо из кода? зачем эта промежуточная обработка?
Ну, я могу один случай придумать, когда это лишним не будет — формулы,
более сложные чем a+b. А через doxygen с LaTeX формулы и оформлять
более-менее удобно можно, и читать это нормально после обработки.
.
. Потому что тебе трубно будет работать с чужим кодом. Я тоже приверженец своего стиля, но я его не навязываю другим. Вообще такой подход к отбору кандидатов, смахивает на собеседование с HR, а не с программистом. Вот когда чел пишет совсем без стиля(а такие кстати есть), т.е. пишет буковки как придется, тогда согласен, с ним трудно писать код, а тем более его саппортить.
