On Thursday, 5 February 2015 at 06:26:17 UTC, Meta wrote:
I've found that the more years of experience I have under my
belt, the less documentation I wrote. When I was starting out I
was very diligent in doing everything the Correct Way so as to
cultivate good habits. I'd find my regression over the years
more alarming if I cared enough.
$0.02:
I personally use contracts quite a lot to tighten the screws on
my interfaces. I don't like writing documentation, mostly on
account of I refactor so aggressively it winds up being wasted
effort in a lot of cases (though I do make notes when I think
something is complex enough to forget or unlikely to change), so
instead I opt to "document" via unittest and assert messages in
contracts.
One of my main internal packages consists of a set of mixin
templates that generate operators from supplied primitives. The
release runtime is meant to be light, and mostly offers syntactic
sugar (more importantly, unified interfaces with predictable
semantics) so code for each layer winds up being between 1:1 and
60:1 contract to body.
From a documentation perspective, being able to open up the "out"
block and see that the enclosing struct's length values must
reflect the values passed to the allocation primitive is nice.
Being able to open up the "body" block and see, without the
clutter of all the bounds checks and whatnot, opIndex just
forwards the call to the access primitive in one line - also nice.
I love dbC in D. I think in/out makes things clean and obvious. I
could care less about the line count, I use code-folding anyway.
