I add a boilerplate to each function definition that
declares constraints on inputs, expectations of outputs,
performance issues, etc. I use this to add invariants
to the code to detect/enforce these conditions.
But, there is nothing that ensures that I've done
this -- other than discipline.
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.
[This makes RPC much more effective but can also
benefit traditional ftn invocations]
Any pointers to similar schemes? I've been looking
through CORBA et al. for hints but they seem to
focus on bigger machines (where there is more tolerance
over data types and more overhead expected).
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.
On 2022-06-27, David Brown <david.brown@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.
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.
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.
On 2022-06-27, David Brown <david.brown@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.
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.
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.
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.
Often these templates generated documents by using something like
Doxygen.
On 6/27/2022 8:18 AM, Grant Edwards wrote:
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?
On 27 Jun 2022 at 17:18:07 CEST, "Grant Edwards" <invalid@invalid.invalid> wrote:
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.
Often these templates generated documents by using something like
Doxygen.
For the last 20 years or so, virtually all our manuals have been created
by our own "literate programming" system called DocGen. DocGen is
optimised for Forth, but it would not be a big job to write a version for C.
DocGen diverges from Doxygen and friends in a several ways. In
particular it does not need template blocks. If your C code is so bad
that another programmer cannot read the declaration, you need far
more help than DocGen or Doxgen can give you. The main entry
for a function follows the declaration
float someFunc( int how, double x, double y )
// *G The purpose of *\c{someFunc} is ...
// ** ...
{
...
}
The lines starting // *x are formal comments to be processed by
DocGen. The *X parts are formatting commands, and the *\<name>{}
parts are text macros.
The ideas behind DocGen are that the code and the documentation
are never separated, and that the DocGen portion is not much larger
than the descriptive comments you should have in your code anyway.
Keeping the code in sync with the documentation is a matter of
company culture and management.
Whenever we receive third party code to include in our products,
we *always* DocGen it before release and we *always* find some
bugs. Overall, I estimate that writing the documentation alongside
the code costs about 10% extra, paid for by the reduction in bug level.
are never separated, and that the DocGen portion is not much larger
than the descriptive comments you should have in your code anyway.
Keeping the code in sync with the documentation is a matter of
company culture and management.
Sadly, my experience has been that folks aren't keen on keeping
docs and code in sync and the more documentation, the less it
tends to track the code. Especially for projects that "evolved"
instead of being "designed". (each refactor requiring a substantial reframing of the commentary)
On 28 Jun 2022 at 14:49:41 CEST, "Don Y" <blockedofcourse@foo.invalid> wrote:
The ideas behind DocGen are that the code and the documentation
are never separated, and that the DocGen portion is not much larger
than the descriptive comments you should have in your code anyway.
Keeping the code in sync with the documentation is a matter of
company culture and management.
Sadly, my experience has been that folks aren't keen on keeping
docs and code in sync and the more documentation, the less it
tends to track the code. Especially for projects that "evolved"
instead of being "designed". (each refactor requiring a substantial
reframing of the commentary)
As others have said it needs discipline. Discipline comes from
management. As the boss, I have made it quite clear that use
of DocGen is a requirement to work at the company. In turn
it is my job to ensure that people know how to use the tool.
On 6/28/2022 7:35 AM, Stephen Pelc wrote:
As others have said it needs discipline. Discipline comes from
management. As the boss, I have made it quite clear that use
of DocGen is a requirement to work at the company. In turn
it is my job to ensure that people know how to use the tool.
You can "legislate" the use of a tool or adherence to a standard.
But, these are subjective issues -- not like "derate all caps by
40%" (which can be independently, mathematically verified). You
rely on individual "employees" for their judgement as to the
effectiveness of their documentation. Likewise, the efficacy
of their test/validation efforts.
On 28 Jun 2022 at 20:33:42 CEST, "Don Y" <blockedofcourse@foo.invalid> wrote:
On 6/28/2022 7:35 AM, Stephen Pelc wrote:
As others have said it needs discipline. Discipline comes from
management. As the boss, I have made it quite clear that use
of DocGen is a requirement to work at the company. In turn
it is my job to ensure that people know how to use the tool.
You can "legislate" the use of a tool or adherence to a standard.
But, these are subjective issues -- not like "derate all caps by
40%" (which can be independently, mathematically verified). You
rely on individual "employees" for their judgement as to the
effectiveness of their documentation. Likewise, the efficacy
of their test/validation efforts.
Followed by lots more pointless whining.
Changing company culture is really hard, even for my own
company. I'm an electronics engineer by training, and I have
been writing software since 1967, and I still write production
code.
I may not have fired people directly for not being good enough,
but I have certainly strongly encouraged them to get another job.
Sysop: | Keyop |
---|---|
Location: | Huddersfield, West Yorkshire, UK |
Users: | 308 |
Nodes: | 16 (2 / 14) |
Uptime: | 93:41:42 |
Calls: | 6,923 |
Calls today: | 1 |
Files: | 12,383 |
Messages: | 5,434,168 |