On Tue, Feb 26, 2013 at 11:53:11AM -0800, Walter Bright wrote: > On 2/25/2013 11:56 PM, foobar wrote: > >DDoc isn't part of the language but rather part of the compiler, > >nevertheless it has its downsides. [...] > >unittest is worse, > > I think you're missing something gigantic. Before D had ddoc, the > documentation for Phobos was TERRIBLE - it was mostly missing, and > the rest would describe something that had no resemblance to what > the code did. Adding Ddoc completely revolutionized this. It's like > night and day. Sure, you can pick at Ddoc's flaws all day, but > without Ddoc, the Phobos documentation would have remained utter > s**t.
I have to say that even though ddoc hasn't quite grown on me yet, I did start using it recently for one of the generic modules I was working on for my personal projects, and, for all its warts and shortcomings, it's incredibly handy, and actually makes you *want* to write documentation for your code. I mean, it's right there, you just have to type it in and you'll get the docs. YMMV, but personally I find ddoc actually very helpful in improving the general quality of D code. My D code has improved because having to write docs for functions actually made me think about some corner cases I would've overlooked otherwise. > Yes, one could use Doxygen. One could hope an up-to-date version > exists on all the platforms D is on. One could nag people to use it. > One could argue with people who wanted to use a different doc > generator. And one could look at typical C and C++ projects, which use > no documentation generator at all, and pretty much have no > documentation or have documentation as bad as the pre-Ddoc Phobos > docs. I've tried to use Doxygen before. I hate it. It feels like something patched onto a deficient language, and just doesn't integrate well with the workflow (nobody wants to run make docs when it might potentially lengthen the code-compile-test cycle). Whereas ddoc is done as you compile, so you get it "for free". It assumes users actually have it installed, which most don't, and ... the number of C/C++ projects I've seen the source code of, that uses Doxygen, can be counted on one hand. Maybe less. Most just have outdated comments (if at all!), haphazardly formatted, and usually inaccurate because people have patched changes without updating the comments (nobody wants to, because there's no standard format, and nobody wants to edit typo-filled non-punctuated remarks on the off-chance that it might actually be saying something important). > Having Ddoc always there, always installed, always up to date, with > literally zero effort, tips the balance. It gets used. It raised the > bar on what is acceptable D code - it looks wrong without Ddoc > documentation. By tipping the balance I mean it *revolutionized* D > code. +1. Well, +0.5, 'cos I'm still not fully sold on ddoc yet... but I'm starting to. > The same goes for unittest. How many C/C++ projects have you run > across that have unit tests? Again, yes, you can use 3rd party tools > (of which there are a plethora). You can try to use multiple > libraries that use different unit test frameworks. You can look at > Phobos before unittest and see that it was pretty much completely > untested. > > Unittest in the language, always there, always installed, zero > effort, completely changed the game. I'm very pleased at the depth > and breadth of unittests in Phobos. I have no doubt that would not > have happened without unittest. Yeah, unittests have improved the quality of my code by leaps and bounds. Especially in the area of regressions: sure you don't need built-in unittests to get it right the first time, but what about when you made the 500-line diff adding a brand new feature? Most of the time, when I do that, I introduce tons of regressions that I'm not even aware of until I run into them much later. Nothing is a better wakeup call than patching the diff in, compiling with -unittest, running the program, and oops, unittest failure left, right, and center! Better fix all those regressions! Result: you find bugs early, before they show up in production environments. > Sure, you can pick all day at the flaws of unittest, but you'd be > missing the point - without builtin unittest, there'd be nothing to > pick at, because people would not have unit tests. Yep, that's me. I hated unittesting, 'cos I felt it was a waste of time. I had to put the code on hold, switch to a different language made for unittesting (like python or Tcl/Expect or whatever), write tests in a different directory, which then get out of sync with the latest code, and become too troublesome to update, so you disable them then forget to re-enable them later after things are updated, etc.. It's just lots of needless overhead. But D's built-in unittests, for all their warts and shortcoming, have the benefit of being right there, ready to use, and guaranteed to be runnable by whoever is compiling the code (don't have to worry about people not having Expect/python/whatever installed, so contributors have no excuse to not run them, etc.). Plus, it's in pure D syntax, so my brain doesn't have to keep switching gears, which means I'm more likely to actually write them. And there's no need of painstakingly building lots of scaffolding for unittesting, which is the problem when I begin most projects 'cos the code is too small to justify the effort of setting up a unittesting environment, but then once the code grows, too much code isn't unittested as they should be, and by then, it's kinda too late to remember all the corner cases you need to check for. As is the case with ddocs, writing unittests while you're coding makes you think about corner cases you may have overlooked, all while the code is fresh in your mind, as opposed to 20 minutes later when that potentially dangerous pointer manipulation may have been forgotten and lurks in the code until much later. So yeah. Complain as you may about the flaws of D's unittests, but they sure have helped improve my code significantly. > >Additional such problems - the AA issue which has been going own for > >years now. The endless discussions regarding tuples. It seems that > >D strives to bloat the language with needless features that really > >should have been standardized in the library and on the other hand > >tries to put in the library things that really ought to be built into > >the language to benefit from proper integration and syntax. > > A little history is in order here. AA's were built in to the > language from the beginning, a result of my experience with how > incredibly useful they were in javascript. This was many years > before D had templates. There was no other way at the time to > implement them in a nice manner (try doing it in C, for example). > > D's improving generics has enabled them to be redone as library > features. [...] Not to mention that many of current AA issues were introduced later when people tried to extend it in ways not originally conceived. Like supporting ranges -- which required the schizophrenic duplication of internal data structures in object_.d -- a horrible idea, to say the least, but I can totally sympathize with why it would be preferable to holding off and waiting indefinitely for the ideal solution, and thus having zero range support for a looong time. T -- Stop staring at me like that! You'll offend... no, you'll hurt your eyes!
