[fpc-pascal] Please someone explain this to me

[Jürgen Hestermann]

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.