[OT] Generating distribution of N dice rolls

[H. S. Teoh]

On Fri, Nov 11, 2022 at 03:34:31AM +0000, Max Haughton via Digitalmars-d wrote:
> On Friday, 11 November 2022 at 01:47:54 UTC, H. S. Teoh wrote:
[...]
> > See, this is proof that documentation goes out of sync with the
> > code. We need a new innovation, along the lines of built-in
> > unittests, to revolutionize keeping docs up-to-date with the code.
[...]
> Built in AI model? (I joke but this is probably the future, whoever
> gets it right will make a lot of money).
> 
> Describing what code *does* is actually already relatively doable
> using contemporary AI techniques, but that isn't documentation (or at
> least isn't good documentation, I don't know that `x + y` adds two
> numbers together.

I don't think AI will ever be able to replace real documentation. It can
describe what the code does, but like you said, that isn't good
documentation.  I mean, I already know `x + y` adds two numbers (if I
didn't, I shouldn't be touching the code in the first place). The AI
saying this for me, doesn't really add any value.  What makes good
documentation is to explain *why* I'm adding two numbers.  I don't think
any AI will be able to divine my intention in adding two numbers; that
has to be written by the programmer.

One of the factors that make D unittests so awesome is the fact that you
can put them right in the same source file as you're coding in, and in
fact, quite often right next to the function it's documenting.  This
proximity is what increases the likelihood that people are more likely
to write unittests, and more inclined to keep them up-to-date (as
opposed to, y'know, opening up an external unittest file and commenting
out / disabling a troublesome test just to get things to run). Even if
somebody `version(none)`'d out a unittest, it's still sitting right
there in the source file, sticking out like a sore thumb and begging
silently but persistently "fix me, fix me, you know you should!".

One idea that comes to mind w.r.t. documentation, is if the docs can be
written not only in the comment header, but inside the function body,
next to the block of code responsible for some particular task. It would
have some tags to help ddoc figure out where in the doc block it goes,
so that there is some control over order of presentation.  But the
comment would be sitting next to the offending code, so when somebody
changes the code, the comment would be staring right at them, "update
me, update me, c'mon I know you know you should!".


T

-- 
Why do conspiracy theories always come from the same people??