Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
| From | Ian Collins <ian-news@hotmail.com> |
|---|---|
| Newsgroups | comp.lang.c |
| Subject | Re: Readability part II - comments |
| Date | 2015-04-19 08:43 +1200 |
| Message-ID | <cpftvhFl1o8U5@mid.individual.net> (permalink) |
| References | (2 earlier) <slrnmivseq.2ot.grahn+nntp@frailea.sa.invalid> <mgqhae$r9r$1@dont-email.me> <slrnmj3uq1.2ot.grahn+nntp@frailea.sa.invalid> <cpegg6Fl1o8U3@mid.individual.net> <slrnmj4kv9.2ot.grahn+nntp@frailea.sa.invalid> |
Jorgen Grahn wrote:
> On Sat, 2015-04-18, Ian Collins wrote:
>> Jorgen Grahn wrote:
>>> On Fri, 2015-04-17, David Brown wrote:
>>>> On 16/04/15 19:31, Jorgen Grahn wrote:
>>>>> On Thu, 2015-04-16, Ian Collins wrote:
>>>>>>
>>>>>> For Doxygen comments, before the thing they describe in a header.
>>>>>
>>>>> I prefer to keep them with the definition of a function, i.e. often in
>>>>> a source file. It's much easier to remember to update the
>>>>> documentation then, and to detect if someone forgot to.
>>>>
>>>> The general rule is that people /using/ the function should only look at
>>>> information in the header file, while people /implementing/ or
>>>> /maintaining/ the code can look in the source file. Use that to
>>>> determine what comments (doxygen or otherwise) go in which file.
>>>
>>> I don't agree with that rule. As a user of foo.{c,h} I prefer to
>>> start with the header file, but jump to the definition of the function
>>> and find its documentation there. I may also read some of the
>>> implementation, if the docs have white spots.
>>>
>>> Part of the reason is I don't trust people to update documentation far
>>> away from the code change. I don't trust myself to do that.
>>
>> It's a pity comments don't have unit tests!
>
> Yes ...
>
> You mentioned elsewhere, I think, that you see unit tests as
> documentation, guaranteed not to be out of date. I hear that now and
> then, but I seem unable to use them that way: they remind me too much
> of riddles. You have tests which say the thing has to be gray, weigh
> 2,000 kg and live in Africa; then you have to deduce yourself that the
> answer is "elephant".
Those tests must have been written after the fact!
> Although it's true that unit tests complement the documentation, just
> like example code. If I need to use a new, unfamiliar interface and
> there are well-written unit tests, I will certainly study them. (And
> maybe modify them to see what happens, if I am unsure about some
> aspect.)
The beauty of comprehensive (in my world, comprehensive => written
before the code) unit tests is they provide both the requirements
documentation and example code.
--
Ian Collins
Back to comp.lang.c | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
Readability part II - comments Tim Rentsch <txr@alumni.caltech.edu> - 2015-04-15 11:48 -0700
Re: Readability part II - comments David Brown <david.brown@hesbynett.no> - 2015-04-16 10:42 +0200
Re: Readability part II - comments Ian Collins <ian-news@hotmail.com> - 2015-04-16 22:01 +1200
Re: Readability part II - comments Richard Heathfield <rjh@cpax.org.uk> - 2015-04-16 11:40 +0100
Re: Readability part II - comments James Kuyper <jameskuyper@verizon.net> - 2015-04-16 07:09 -0400
Re: Readability part II - comments Richard Heathfield <rjh@cpax.org.uk> - 2015-04-16 12:18 +0100
Re: Readability part II - comments James Kuyper <jameskuyper@verizon.net> - 2015-04-16 07:36 -0400
Re: Readability part II - comments Richard Heathfield <rjh@cpax.org.uk> - 2015-04-16 12:43 +0100
Re: Readability part II - comments James Kuyper <jameskuyper@verizon.net> - 2015-04-16 08:00 -0400
Re: Readability part II - comments Richard Heathfield <rjh@cpax.org.uk> - 2015-04-16 13:21 +0100
Re: Readability part II - comments James Kuyper <jameskuyper@verizon.net> - 2015-04-16 10:54 -0400
Re: Readability part II - comments Richard Heathfield <rjh@cpax.org.uk> - 2015-04-16 16:45 +0100
Re: Readability part II - comments Steve Thompson <stevet810@gmail.com> - 2015-04-16 18:00 +0000
Re: Readability part II - comments Malcolm McLean <malcolm.mclean5@btinternet.com> - 2015-04-16 04:52 -0700
Re: Readability part II - comments Ben Bacarisse <ben.usenet@bsb.me.uk> - 2015-04-16 16:40 +0100
Re: Readability part II - comments Malcolm McLean <malcolm.mclean5@btinternet.com> - 2015-04-18 03:33 -0700
Re: Readability part II - comments Les Cargill <lcargill99@comcast.com> - 2015-04-16 21:10 -0500
Re: Readability part II - comments Ben Bacarisse <ben.usenet@bsb.me.uk> - 2015-04-16 17:20 +0100
Re: Readability part II - comments Richard Heathfield <rjh@cpax.org.uk> - 2015-04-16 17:53 +0100
Re: Readability part II - comments Steve Thompson <stevet810@gmail.com> - 2015-04-16 17:34 +0000
Re: Readability part II - comments Richard Heathfield <rjh@cpax.org.uk> - 2015-04-16 19:15 +0100
Re: Readability part II - comments Steve Thompson <stevet810@gmail.com> - 2015-04-16 18:25 +0000
Re: Readability part II - comments David Brown <david.brown@hesbynett.no> - 2015-04-16 12:45 +0200
Re: Readability part II - comments Jorgen Grahn <grahn+nntp@snipabacken.se> - 2015-04-16 17:31 +0000
Re: Readability part II - comments David Brown <david.brown@hesbynett.no> - 2015-04-17 10:48 +0200
Re: Readability part II - comments Jorgen Grahn <grahn+nntp@snipabacken.se> - 2015-04-18 06:35 +0000
Re: Readability part II - comments Ian Collins <ian-news@hotmail.com> - 2015-04-18 19:47 +1200
Re: Readability part II - comments Jorgen Grahn <grahn+nntp@snipabacken.se> - 2015-04-18 12:54 +0000
Re: Readability part II - comments Ian Collins <ian-news@hotmail.com> - 2015-04-19 08:43 +1200
Re: Readability part II - comments Ian Collins <ian-news@hotmail.com> - 2015-04-19 12:36 +1200
Re: Readability part II - comments Greg Martin <greg.at.softsprocket@dot.com> - 2015-04-20 13:58 +0000
Re: Readability part II - comments Greg Martin <greg.at.softsprocket@dot.com> - 2015-04-20 21:02 +0000
Re: Readability part II - comments Greg Martin <greg.at.softsprocket@dot.com> - 2015-04-20 23:38 +0000
Re: Readability part II - comments Greg Martin <greg.at.softsprocket@dot.com> - 2015-04-21 01:12 +0000
Re: Readability part II - comments Ian Collins <ian-news@hotmail.com> - 2015-04-21 16:39 +1200
Re: Readability part II - comments Richard Damon <Richard@Damon-Family.org> - 2015-04-18 14:21 -0400
Re: Readability part II - comments August Karlstrom <fusionfile@gmail.com> - 2015-04-16 19:18 +0200
Re: Readability part II - comments Greg Martin <greg.at.softsprocket@dot.com> - 2015-04-17 16:16 +0000
Re: Readability part II - comments John Bode <jfbode1029@gmail.com> - 2015-04-20 09:19 -0700
Re: Readability part II - comments asetofsymbols@gmail.com - 2015-04-20 11:15 -0700
Re: Readability part II - comments David Kleinecke <dkleinecke@gmail.com> - 2015-04-20 11:37 -0700
Re: Readability part II - comments Steve Thompson <stevet810@gmail.com> - 2015-04-22 02:02 +0000
Re: Readability part II - comments David Kleinecke <dkleinecke@gmail.com> - 2015-04-22 09:48 -0700
Re: Readability part II - comments Tim Rentsch <txr@alumni.caltech.edu> - 2015-04-21 12:40 -0700
Re: Readability part II - comments Greg Martin <greg.at.softsprocket@dot.com> - 2015-04-21 21:24 +0000
Re: Readability part II - comments Tim Rentsch <txr@alumni.caltech.edu> - 2015-04-23 21:57 -0700
Re: Readability part II - comments "Skybuck Flying" <skybuck2000@hotmail.com> - 2015-04-24 09:14 +0200
csiph-web