On 6/27/2022 8:18 AM, Grant Edwards wrote:
> On 2022-06-27, David Brown <
david...@hesbynett.no> wrote:
>> On 26/06/2022 21:35, Don Y wrote:
>>> I add a boilerplate to each function definition that
>>> declares constraints on inputs, expectations of outputs,
>>> performance issues, etc.
>
>> What programming language are you using? If your answer is "C",
>> it's wrong.
>>
>> If you are just putting these things in comments, then they will get out
>> of sync with the code.
>
> I'd have to agree. I've worked with many projects and third-party
> libraries over the decades which had a big template of comments for
> every function which described the input/ouput parameters, return
> value, global variables used, and so on.
You perhaps missed the balance of my post:
"I use this to add invariants to the code to detect/enforce
these conditions."
...
"I'm looking at ways to create an IDL that will allow for
more specific criteria to be included in the declaration
that could also drive the IDL compiler to add suitable
invariants as applicable."
I.e., a "specification language" FROM WHICH the IDL compiler can
(I am currently using an enhanced form of OCL) create the code -- in
whatever language binding is selected AT COMPILE TIME.
So, if I say:
month > 0
AND
month < 13
as constraints *in* the function's "prototype", then
the IDL compiler generates an invariant that throws a
"range error" OR panics (depending on IDL compiler switch)
AT RUN TIME if the function is invoked with the "month"
parameter not compliant with those constraints.
The OCL *documents* the calling constraints of the
function (and its return values) in a language neutral
manner. I.e., you could create an ASM binding for the
IDL compiler's output and the programmer would be
none the wiser.
The advantage of driving the code generator this way is
the "documentation" creates the code -- if you don't
*document* (declare) a constraint, then it isn't enforced.
It ensures the code and documentation agree and that
every bit of documentation has a corresponding bit of
code (but not necessarily the other way around)
> Often these templates generated documents by using something like
> Doxygen.
>
> And on _every_single_one_ of those projects and libraries, the
> comments were wrong often enough that nobody who knew which way was up
> paid any attention to them. If you wanted to know what the parameters
> were for, what the function returned, and so on, you read the C code.
You *always* read the code. The OCL declarations *are* effectively
code; the stub generated *will* reference "month" and not "moth"
or "monday" (or whatever). But, they are formally expressed in a
syntax defined by the "specification language" (~OCL in my case).
Invoking the exemplar with a month of "13" could possibly work
within the body of the function, as implemented -- perhaps treating
this as year++ with month=1 -- but the invariant won't let the
value *into* the function. Because the intent was *not* to invoke
the function with a bogus month value.
19A0 is not 2000!
The whole point is to encourage the developer to codify (in OCL)
the constraints on the code so that the IDL compiler can create
the actual instruction sequence (in the language bound to that set
of command line switches) to enforce those constraints.
*But*, you are still reliant on discipline; if the developer
doesn't declare those constraints, then the compiler can't create
any code to do this and simply is resigned to creating the code
to marshal arguments and pack the message for transport.
One can casually inspect the IDL files to see if there is an
abundance -- or a dearth -- of constraints without having to
parse countless source files. The IDL files *generate* the
"header" files so you can't skip that step.
Additionally, it can generate the sever side stubs (in whichever
language binding is appropriate *there*) to unpack and parse
the message, convert the arguments to whatever format is "native"
for the server (knowing that their values are "legitimized" by
the client-side stub) and hand them off to the server-side
function.
[similarly handling the return message]
> A lot of the time, even the numbers and names of the parmeters
> described in the template didn't match the code.
>
> The auto-generated PDF documents and HTML web site looked nice, though.
There's no point in generating "prose" from such a specification.
What are you going to do, pretty-print the generated stubs? Or,
the OCL-expressed constraints?