Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
Groups > comp.arch.embedded > #31119
| From | Grant Edwards <invalid@invalid.invalid> |
|---|---|
| Newsgroups | comp.arch.embedded |
| Subject | Re: Ftn I/Os documentation best practices |
| Date | 2022-06-27 15:18 +0000 |
| Organization | PANIX Public Access Internet and UNIX, NYC |
| Message-ID | <t9chnf$kve$1@reader2.panix.com> (permalink) |
| References | <t9acer$d1t$1@dont-email.me> <t9bmlm$bic9$1@dont-email.me> |
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. -- Grant
Back to comp.arch.embedded | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
Ftn I/Os documentation best practices Don Y <blockedofcourse@foo.invalid> - 2022-06-26 12:35 -0700
Re: Ftn I/Os documentation best practices David Brown <david.brown@hesbynett.no> - 2022-06-27 09:36 +0200
Re: Ftn I/Os documentation best practices Grant Edwards <invalid@invalid.invalid> - 2022-06-27 15:18 +0000
Re: Ftn I/Os documentation best practices David Brown <david.brown@hesbynett.no> - 2022-06-27 19:52 +0200
Re: Ftn I/Os documentation best practices Don Y <blockedofcourse@foo.invalid> - 2022-06-27 14:34 -0700
Re: Ftn I/Os documentation best practices David Brown <david.brown@hesbynett.no> - 2022-06-28 13:48 +0200
Re: Ftn I/Os documentation best practices Stephen Pelc <stephen@vfxforth.com> - 2022-06-28 08:30 +0000
Re: Ftn I/Os documentation best practices Don Y <blockedofcourse@foo.invalid> - 2022-06-28 05:49 -0700
Re: Ftn I/Os documentation best practices Stephen Pelc <stephen@vfxforth.com> - 2022-06-28 14:35 +0000
Re: Ftn I/Os documentation best practices Don Y <blockedofcourse@foo.invalid> - 2022-06-28 11:33 -0700
Re: Ftn I/Os documentation best practices Stephen Pelc <stephen@vfxforth.com> - 2022-06-29 12:36 +0000
Re: Ftn I/Os documentation best practices Don Y <blockedofcourse@foo.invalid> - 2022-06-29 06:39 -0700
csiph-web