Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.c > #60097 > unrolled thread

Readability part II - comments

Back to article view | Back to comp.lang.c

Contents

  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

Page 2 of 3 — ← Prev page 1 [2] 3  Next page →

#60167

On 16/04/15 18:34, Steve Thompson wrote:
> On Thu, Apr 16, 2015 at 11:40:11AM +0100, Richard Heathfield wrote:
>> On 16/04/15 11:01, Ian Collins wrote:
>> >Tim Rentsch wrote:
>>
>> <snip>
>>
>> >  > How should comments be written?
>> >
>> >In clear, correct <insert project language here> with correct spelling,
>> >grammar and punctuation.
>>
>> 100% performance is an unrealisable goal, but very high conformance
>> levels should be part of the contract, and failure to meet those targets
>> should be sufficient grounds for termination of that contract. Why
>> should we trust people to write statements in a computer language
>> correctly if they cannot consistently demonstrate fluent and proper use
>> of the human language used by project personnel?
>
> Because otherwise one might be unable to hire enough staff/consultants
> to man one's projects.

And so we might have to cut back on the projects we undertake, and focus 
on doing a Good Job on those projects. Never mind the width - feel the 
quality.

> You've heard the phrase "can't get good help these days"?  That
> sentiment only becomes more true over time as the standard of public
> education continues to slide.

Right.

>
> This will offend anyone who is deeply religious, but my understanding
> of public education policy is that childhood education is deliberately
> hobbled precisely for the reason that organized religion requires
> masses of poorly educated credulous non-thinkers.  Being a mechanism
> of social control, the "priesthood" inform the sheeple how they are
> to think and act and they do not want their sheeple to consider too
> closely how they are being directed by their leaders or for what
> reasons.

That doesn't offend me in the slightest (although I would probably 
qualify as "deeply religious" in most people's eyes), partly because I'm 
not easily offended but also because the above bears not even the 
slightest relation to my own experience of what you would describe as 
organized religion.

>
>> (This policy should also apply to /anyone/ earning an above-average
>> wage. If we can sneak this idea into employment legislation...)
>
> Good luck with that.  The guild of lawyers would be the first to
> challenge the notion that competence and clarity of language ought to
> be a criterion of professional association, and so you would lose
> unconditionally.

Ach, you're right again. I'd forgotten about the lawyers.

-- 
Richard Heathfield
Email: rjh at cpax dot org dot uk
"Usenet is a strange place" - dmr 29 July 1999
Sig line 4 vacant - apply within

[toc] | [prev] | [next] | [standalone]

#60171

On Thu, Apr 16, 2015 at 07:15:56PM +0100, Richard Heathfield wrote:
> On 16/04/15 18:34, Steve Thompson wrote:
> >On Thu, Apr 16, 2015 at 11:40:11AM +0100, Richard Heathfield wrote:
> >>On 16/04/15 11:01, Ian Collins wrote:
> >>>Tim Rentsch wrote:
> >>
> >><snip>
> >>
> >>>  > How should comments be written?
> >>>
> >>>In clear, correct <insert project language here> with correct spelling,
> >>>grammar and punctuation.
> >>
> >>100% performance is an unrealisable goal, but very high conformance
> >>levels should be part of the contract, and failure to meet those targets
> >>should be sufficient grounds for termination of that contract. Why
> >>should we trust people to write statements in a computer language
> >>correctly if they cannot consistently demonstrate fluent and proper use
> >>of the human language used by project personnel?
> >
> >Because otherwise one might be unable to hire enough staff/consultants
> >to man one's projects.
> 
> And so we might have to cut back on the projects we undertake, and focus 
> on doing a Good Job on those projects. Never mind the width - feel the 
> quality.
> 
> >You've heard the phrase "can't get good help these days"?  That
> >sentiment only becomes more true over time as the standard of public
> >education continues to slide.
> 
> Right.
> 
> >
> >This will offend anyone who is deeply religious, but my understanding
> >of public education policy is that childhood education is deliberately
> >hobbled precisely for the reason that organized religion requires
> >masses of poorly educated credulous non-thinkers.  Being a mechanism
> >of social control, the "priesthood" inform the sheeple how they are
> >to think and act and they do not want their sheeple to consider too
> >closely how they are being directed by their leaders or for what
> >reasons.
> 
> That doesn't offend me in the slightest (although I would probably 
> qualify as "deeply religious" in most people's eyes), partly because I'm 
> not easily offended but also because the above bears not even the 
> slightest relation to my own experience of what you would describe as 
> organized religion.

The practice of religion is quite subjective, and it is obvious to say
that the experience of the ascetic is considerably different from the
experience of the television evangelical or the Archbishop of
Canterbury and his support staff.

> >>(This policy should also apply to /anyone/ earning an above-average
> >>wage. If we can sneak this idea into employment legislation...)
> >
> >Good luck with that.  The guild of lawyers would be the first to
> >challenge the notion that competence and clarity of language ought to
> >be a criterion of professional association, and so you would lose
> >unconditionally.
> 
> Ach, you're right again. I'd forgotten about the lawyers.

They should be forgotten, unfortunately the profession is all but a
licence to print money and is consequently attractive to people who
do not wish to work for a living.  (Unless 'work' is to be defined as
'stealing from the citizenry'.)



Regards,

Steve Thompson

-- 
"If I had a nickel for every time some idiot called me about a
computer problem that turned out to be user error, I would be able to
retire and spend the rest of my days cultivating clues in my backyard
hillside garden."  -- MysteryDog in 24hoursupport.helpdesk.

[toc] | [prev] | [next] | [standalone]

#60125

On 16/04/15 12:01, Ian Collins wrote:
> Tim Rentsch wrote:
>> What makes code readable?
>>
> <snip>
>>
>> To start things going, some general questions.
> 
>> What kinds of comments are important?
> 
> That depends on the context.  Most projects I have worked on prefer
> reasonably verbose, stylised Doxygen comments in headers and a bit of a
> free for all in source files.

That's often a good balance.  Headers are for people using the code -
the source files only need to be seen by implementers and maintainers,
and can be expected to have a greater knowledge of the system.

> 
> In code, comments should state why something is done, what it is doing
> should be clear from the code.  Any bending of the local coding standard
> should always have a comment.
> 
>> What kinds of comments are better avoided?
> 
> Those that sate the obvious!  

Also comments with typos or spelling mistakes are best avoided :-)

> A particular pet hate of mine is comments
> such as
> 
> // Includes
> 
> // Defines
> 
> // Types
> 
> // External data
> 
> and the like.

I'd add comments in the programmer's native language to the list
(assuming it is not the main language for the developers, of course).

> 
>> Where should comments go?
> 
> For Doxygen comments, before the thing they describe in a header.  For
> code comments, directly before the code they explain.
> 
>> How should comments be written?
> 
> In clear, correct <insert project language here> with correct spelling,
> grammar and punctuation.
> 
>> How should commenting facilities be used?
> 
> ?
> 
>> In what ways does commenting interact with readability of the code
> itself?
> 
> Too many or too verbose comments distract from the code.  If code needs
> a comment, think very hard about refactoring the code to express the
> solution without a comment.
> 
>> And again the topic broadening question - how do matters
>> regarding commenting relate to other concerns in the development
>> process (eg, maintenance, testing, documentation, etc)?
> 
> In my view of the coding world, behavioural comments (such as those in
> Jacob's recent strtol code) belong in the test cases, not the
> implementation code.  I like to be able to read code along with its
> tests.  The tests define what the code is doing in code which
> programmers can follow.
> 
> Comments which appear clear and concise the the writer may appear vague
> and ambiguous to a later reader.  Tests never will.
> 
> A time pressured maintenance programmer may overlook updating comments
> so they become incorrect.  Tests never will.
> 

Yes, inconsistent comments are much worse than no comments at all.

[toc] | [prev] | [next] | [standalone]

#60159

On Thu, 2015-04-16, Ian Collins wrote:
> Tim Rentsch wrote:
>> What makes code readable?

...
> > What kinds of comments are better avoided?
>
> Those that sate the obvious!  A particular pet hate of mine is comments 
> such as
>
> // Includes
>
> // Defines
>
> // Types
>
> // External data
>
> and the like.

I see those as a child disease.

Another in the "better avoided" category: information which should
go into your version control commit message.  Not so much because it's
harmful that it's present in the code, but because it's harmful that
it's /not/ present in the commit message.

And a third: paying lip service to Doxygen by not actually providing
any information.  A made-up example, probably with the wrong syntax:

/**
 * @name select
 *
 * @parm nfds : number of fds
 * @parm readfds: fds to read
 * @parm writefds: fds to write
 * @parm exceptfds: fds to have exceptions on
 * @timeout : a struct timeval
 */
int select(int nfds, fd_set *readfds, fd_set *writefds,
           fd_set *exceptfds, struct timeval *timeout);

>> Where should comments go?
>
> 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 drawback is that some things are documented in the headers and
others in the source files.  And I wouldn't do it that way if I wrote
a library, to be distributed as header files and precompiled code.

/Jorgen

-- 
  // Jorgen Grahn <grahn@  Oo  o.   .     .
\X/     snipabacken.se>   O  o   .

[toc] | [prev] | [next] | [standalone]

#60207

On 16/04/15 19:31, Jorgen Grahn wrote:
> On Thu, 2015-04-16, Ian Collins wrote:
> 
> And a third: paying lip service to Doxygen by not actually providing
> any information.  

I think that could be generalised to "paying lip service", regardless of
the type of comment.  But some coding standards encourage such things by
insisting on particular styles of comments even when they are
superfluous - making it hard to see the actual code because the file is
full of verbose but pointless comments to follow the coding standard rules.

> A made-up example, probably with the wrong syntax:
> 
> /**
>  * @name select
>  *
>  * @parm nfds : number of fds
>  * @parm readfds: fds to read
>  * @parm writefds: fds to write
>  * @parm exceptfds: fds to have exceptions on
>  * @timeout : a struct timeval
>  */
> int select(int nfds, fd_set *readfds, fd_set *writefds,
>            fd_set *exceptfds, struct timeval *timeout);
> 
>>> Where should comments go?
>>
>> 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.

> 
> The drawback is that some things are documented in the headers and
> others in the source files.  And I wouldn't do it that way if I wrote
> a library, to be distributed as header files and precompiled code.
> 
> /Jorgen
> 

[toc] | [prev] | [next] | [standalone]

#60295

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:
>> 
>> And a third: paying lip service to Doxygen by not actually providing
>> any information.  
>
> I think that could be generalised to "paying lip service", regardless of
> the type of comment.

Yes, that's a much better way of putting it.  Come to think of it, it
can be extended to the actucal code, too.

...
>>>> Where should comments go?
>>>
>>> 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.

On a higher level, I'm afraid of the situation in a project where
different groups own different subsystems, and treat each other as
customers and library vendors.  It's probably neccessary when things
grow really big, but when they don't, such a mindset is just a
hindrance.

/Jorgen

-- 
  // Jorgen Grahn <grahn@  Oo  o.   .     .
\X/     snipabacken.se>   O  o   .

[toc] | [prev] | [next] | [standalone]

#60297

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!

-- 
Ian Collins

[toc] | [prev] | [next] | [standalone]

#60313

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".

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.)

/Jorgen

-- 
  // Jorgen Grahn <grahn@  Oo  o.   .     .
\X/     snipabacken.se>   O  o   .

[toc] | [prev] | [next] | [standalone]

#60346

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

[toc] | [prev] | [next] | [standalone]

#60357

Stefan Ram wrote:
> Ian Collins <ian-news@hotmail.com> writes:
>> The beauty of comprehensive (in my world, comprehensive => written
>> before the code) unit tests is they provide both the requirements
>> documentation and example code.
>
>    Assume the following requirement,
>
>        »For all long long values x, half( x ) must be
>        a long long value so that
>
>                      | half( x )- x/2.0 |  <  0.51.«.
>
>    What is the unit test for this requirement?
>

Where did I say there would only be one?

-- 
Ian Collins

[toc] | [prev] | [next] | [standalone]

#60525

On 2015-04-18, Stefan Ram <ram@zedat.fu-berlin.de> wrote:
> Ian Collins <ian-news@hotmail.com> writes:
>>The beauty of comprehensive (in my world, comprehensive => written 
>>before the code) unit tests is they provide both the requirements 
>>documentation and example code.
>
>   Assume the following requirement,
>
>       »For all long long values x, half( x ) must be
>       a long long value so that 
>
>                     | half( x )- x/2.0 |  <  0.51.«.
>
>   What is the unit test for this requirement?
>

It's trivial to come up with non-testable examples. It's not a proof for
the lack of value of unit testing, if that's what you're trying to get
at. It's a proof that the specification for the testing must be reasoned
and reasonable.

-- 
http://www.softsprocket.com

[toc] | [prev] | [next] | [standalone]

#60575

On 2015-04-20, Stefan Ram <ram@zedat.fu-berlin.de> wrote:
> Greg Martin <greg.at.softsprocket@dot.com> writes:
>>On 2015-04-18, Stefan Ram <ram@zedat.fu-berlin.de> wrote:
>>> Ian Collins <ian-news@hotmail.com> writes:
>>>>The beauty of comprehensive (in my world, comprehensive => written 
>>>>before the code) unit tests is they provide both the requirements 
>>>>documentation and example code.
>>>Assume the following requirement,
>
>>>    »For all long long values x, half( x ) must be
>>>    a long long value so that 
>>>    | half( x )- x/2.0 |  <  0.51.«.
>
>>>What is the unit test for this requirement?
>>It's trivial to come up with non-testable examples. It's not a proof for
>>the lack of value of unit testing, if that's what you're trying to get
>>at. It's a proof that the specification for the testing must be reasoned
>>and reasonable.
>
>   I was not aware of the fact that the requirement quoted
>   above was »non-testable« and/or not »reasoned«/»reasonable«.
>   Can someone explain why this is so?
>

It is testable, though it /may/ not be practical to test it. I would
consider it practical if I could reliably test a limited set of values
that could be considered representative of the problem, however, since
all numbers >= LLONG_MIN <= LLONG_MAX represents a large set of numbers
it's not reasonable to test all values.


-- 
http://www.softsprocket.com

[toc] | [prev] | [next] | [standalone]

#60592

On 2015-04-20, Stefan Ram <ram@zedat.fu-berlin.de> wrote:
> Greg Martin <greg.at.softsprocket@dot.com> writes:
>>It is testable, though it /may/ not be practical to test it. I would
>>consider it practical if I could reliably test a limited set of values
>>that could be considered representative of the problem, however, since
>>all numbers >= LLONG_MIN <= LLONG_MAX represents a large set of numbers
>>it's not reasonable to test all values.
>
>   I'd like to remind that specifications for functions in the
>   majority of all cases include (implied) all-quantors. Just
>   let me mention two cases:
>
>       sin( double x )
>
>       spec: for all double values x, sin( x ) is the best double-
>       approximation to the mathematical sine of the value x.
>
>       print( double x )
>
>       spec: for all double values x, this will print a decimal
>       numeral that gives the value of x, rounded to 14 decimal digits
>
>   If such common specifications would »not be practical to test«,
>   then tests would be nearly useless.
>

You're being foolish. There is nothing in what you've stated that
assigns a value of lack there of to unit tests. Given a set of
expectations and a reasonable range of values they can be applied and
useful.

>   However, I should not forget what I actually wanted to object to:
>   Your assertion that tests can double as specs.

Where did I assert this?

>   The specs above indeed /can/ be tested, /but/ ususally they
>   cannot be deduced again from the tests,
>   when only the test code is given.
>

Even if the limited examples you've given were the sum total of where
you might consider applying tests they could still be useful in catching
code changes that break expectations.

-- 
http://www.softsprocket.com

[toc] | [prev] | [next] | [standalone]

#60599

On 2015-04-20, Stefan Ram <ram@zedat.fu-berlin.de> wrote:
> Greg Martin <greg.at.softsprocket@dot.com> writes:
>>>However, I should not forget what I actually wanted to object to:
>>>Your assertion that tests can double as specs.
>>Where did I assert this?
>
>   Sorry! I misattributed something to you that was written
>   by Ian Collins. Ian wrote what I replied to first in this
>   subthread:
>
> Ian:
>|The beauty of comprehensive (in my world, comprehensive => written
>|before the code) unit tests is they provide both the requirements
>|documentation and example code.
>
>   So, he seems to think that unit tests provide requirements
>   documentation.
>

Ah, well I can't say that I see more then limited documentation value in
unit tests. Any time I've found myself wading through test cases to
determine how to use some library I have usually given up since unit
tests seem most often to lackcontext or to be in the context of the test
harness itself.

>>Even if the limited examples you've given were the sum total of where
>>you might consider applying tests they could still be useful in catching
>>code changes that break expectations.
>
>   I would never deny that unit tests are useful!
>

Proof once again that context is everything!

-- 
http://www.softsprocket.com

[toc] | [prev] | [next] | [standalone]

#60601

Stefan Ram wrote:
> Greg Martin <greg.at.softsprocket@dot.com> writes:
>>> However, I should not forget what I actually wanted to object to:
>>> Your assertion that tests can double as specs.
>> Where did I assert this?
>
>    Sorry! I misattributed something to you that was written
>    by Ian Collins. Ian wrote what I replied to first in this
>    subthread:
>
> Ian:
> |The beauty of comprehensive (in my world, comprehensive => written
> |before the code) unit tests is they provide both the requirements
> |documentation and example code.
>
>    So, he seems to think that unit tests provide requirements
>    documentation.

So do my customers...

-- 
Ian Collins

[toc] | [prev] | [next] | [standalone]

#60332

On 4/16/15 6:01 AM, Ian Collins wrote:
> Tim Rentsch wrote:
>  > What kinds of comments are better avoided?
>
> Those that sate the obvious!  A particular pet hate of mine is comments
> such as
>
> // Includes
>
> // Defines
>
> // Types
>
> // External data
>
> and the like.

I have one use for comments like these, when I create a new file, the 
IDE creates a "blank" file from a template that includes some basic 
structure, like a boiler plate copyright/licensing comment at the 
beginning a file.

The template includes a few comments like this as our coding convention 
prescribes the order of these sorts of items (with allowance to deviate 
with good reason), and the comments make it easier to see where the item 
is supposed to go. Our markers also include an across the page bar to 
make it easier to find these sections.

[toc] | [prev] | [next] | [standalone]

#60156

On 2015-04-15 20:48, Tim Rentsch wrote:
> What kinds of comments are important?

Comments which tell something important that cannot be expressed in code.

> What kinds of comments are better avoided?

Pretty much anything else.


-- August

[toc] | [prev] | [next] | [standalone]

#60245

On 2015-04-16, August Karlstrom <fusionfile@gmail.com> wrote:
> On 2015-04-15 20:48, Tim Rentsch wrote:
>> What kinds of comments are important?
>
> Comments which tell something important that cannot be expressed in code.
>
>> What kinds of comments are better avoided?
>
> Pretty much anything else.
>

I think there's more to it then this, but it does depend on what you are
writing.

If you are creating a library then something like Doxygen becomes
important. IMO, a header that is designed to be visible by client
programmers should document inputs, outputs, side effects if any and
purpose of functions and data structures such that someone using the
library can understand it. If you actually want someone to use the
library then example usage should be included somewhere and that could
be in a web page or readme or both.

If you are writing a utility then documentation should be adequate for
the maintenance of the package but a man page, or web page documenting
usage should also be provided. 

Usage is a part of documentation and can help clarity.


-- 
http://www.softsprocket.com

[toc] | [prev] | [next] | [standalone]

#60533

On Wednesday, April 15, 2015 at 1:48:31 PM UTC-5, Tim Rentsch wrote:
> What makes code readable?
> 

[snip]

> To start things going, some general questions.  What kinds of
> comments are important?  What kinds of comments are better
> avoided?  Where should comments go?  How should comments be
> written?  How should commenting facilities be used?  In what ways
> does commenting interact with readability of the code itself?
> And again the topic broadening question - how do matters
> regarding commenting relate to other concerns in the development
> process (eg, maintenance, testing, documentation, etc)?

First law of documentation: don't document the obvious.
Corollary to the first law: write obvious code.

Remembering that comments must be maintained along with the rest of the
code, it's in everyone's interest to minimize the number of inline
comments, ideally to none at all.  Out-of-date/incorrect comments are 
worse than no comments at all.  Having said that, here are the cases
where I would use inline comments (i.e., not a function or file header
block):

1.  Explaining excessively "tricky" code, ALONG WITH JUSTIFICATION FOR
    SAID TRICKINESS.  For example, "profiling showed this code offered
    20% better performance than the more straightforward version", just 
    so someone like me won't be tempted to clean it up;

2.  Reference to a requirement or standard ("DTED 3 post spacing is 1
    arc second");

3.  Identify areas for further work /* TODO */

As for block comments, I want to see at least the following:

 * A *high-level* description of the function and it's purpose (what
   role does this function serve in the larger system, e.g., 
   "update all the clients whose status has changed in the last
    sixy seconds");

 * A list of inputs, again with a *high-level* description of their
   purpose ("number of items", "seconds to wait", "list of names
   to be updated", etc.);

 * A list of outputs with high-level descriptions;

 * Return values and descriptions;

A list of preconditions and postconditions would be nice as well, but 
I'm not as much of a stickler about that.  I don't care about types
or algorithms in function document blocks.  I care about what role 
this function and its parameters play in the larger system.  

Naturally, there should external requirements and design documents.

I've been convinced that keeping commit history in the file itself (i.e.,
CVS $Id: $ and $Log: $ tags) is a Bad Idea.  That's better tracked in
whatever version control system you're using (and given that tools like
Git don't track per-file history, there's not much point in having it
anyway).  

[toc] | [prev] | [next] | [standalone]

#60552

Yes it is really a problem...
sometimes I comment first of write
the algo in code, just a try of
understand better and then 
write the code...
Is that right? Has These comment
 to be removed?

[toc] | [prev] | [next] | [standalone]

Page 2 of 3 — ← Prev page 1 [2] 3  Next page →

Back to top | Article view | comp.lang.c

csiph-web