Re: Readability part II - comments

From	David Brown <david.brown@hesbynett.no>
Newsgroups	comp.lang.c
Subject	Re: Readability part II - comments
Date	2015-04-16 12:45 +0200
Organization	A noiseless patient Spider
Message-ID	<mgo3qu$3os$1@dont-email.me> (permalink)
References	<kfnwq1d1b4a.fsf@x-alumni2.alumni.caltech.edu> <cp9fk0Ffnp3U4@mid.individual.net>

Show all headers | View raw

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.

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