Am 2016-02-15 um 18:21 schrieb Andreas Schneider:
> Am 2016-02-14 12:42, schrieb Jürgen Hestermann:
>> Here we differ:
>> I expect that a documentation *fully* explains
>> a behaviour of a certain function (or something else),
>> not just some part of it.
> IMHO that would be insane. To a programmer (like you and me) the RTL and the
Compiler are just interfaces. Therefore the documentation describes the contract.
I need not and should not need to know the inner workings. All I need to know is
the required inputs to get a specific output.
> The more of the internals you guarantee, the less you can change later on
which might even make platform portability impossible.
Fully agree, exactly what I was trying to say.
> So again - in my opinion - internals are best left out of documentation.
Therefore *fully* explaining the behavior would be wrong.
I would differentiate between "details" and "internals". Of course, the exact coding
("internals") should not be part of the documentation.
But the "details" - which I would name the behaviour under all (even rare)
circumstances - should be fully documented.
There should be no doubt what I can expect and what not.
But in this forum very often when someone complains about missing or incomplete
documentation he gets the advice to look into the code which IMO is insane
because
1.) the code may change over time
2.) it can have bugs (which I would rely on)
3.) it is often hard to understand if I don't know about the surrounding
concepts and other things.
Also, the documentation is very important for the programmer as it lets him
think about what he is coding (and only the programmer knows what he had in
mind when he coded something). I often found that my code was imcomplete or
otherwise misconcepted as I tried to explain it to someone else.
_______________________________________________
fpc-pascal maillist - fpc-pascal@lists.freepascal.org
http://lists.freepascal.org/cgi-bin/mailman/listinfo/fpc-pascal
