Re: Readability part II - comments

From	Steve Thompson <stevet810@gmail.com>
Newsgroups	comp.lang.c
Subject	Re: Readability part II - comments
Date	2015-04-22 02:02 +0000
Organization	Friends of the Galactic Collective
Message-ID	<fBk1iB.uHu.29E6P@gmail.com> (permalink)
References	<kfnwq1d1b4a.fsf@x-alumni2.alumni.caltech.edu> <e7280fa7-b3d1-4585-95e4-4fd93ba15d30@googlegroups.com>

Show all headers | View raw

On Mon, Apr 20, 2015 at 11:37:14AM -0700, David Kleinecke wrote:
> On Wednesday, April 15, 2015 at 11:48:31 AM UTC-7, Tim Rentsch wrote:
> > What makes code readable?
> > 
> > In a recent thread this term came up, and it got me thinking
> > about the different sorts of qualities and aspects that are
> > commonly lumped together under the general term "readability".
> > Of course I have my own ideas (some more definite than others) on
> > the subject, but it got me wondering what other folks might have
> > to say about it.  So I am writing this to invite your responses,
> > ideas, ramblings, thoughts, orations, monographs and diatribes,
> > on the general question of what makes code readable, taking
> > commenting into account.  Three suggested guidelines:
> > 
> > (1) The remarks should apply to programs written in C.  (They may
> >     also apply to programs written in some other language(s), but
> >     they should apply to C programs.)
> > 
> > (2) Please let's not degenerate into dogmatic arguments.  If
> >     someone thinks '/*...*/' comments are "more readable" than
> >     '//' comments, or vice versa, simply say so and move on
> >     (explaining why one thinks so is okay, making an argument
> >     about what someone else should think is .. an argument).
> >     There is no point in arguing about subjective reactions.
> > 
> > (3) In this thread please limit remarks to matters related to
> >     commenting, without regard to questions just about code.  The
> >     related area regarding code sans commenting I will bring up
> >     in a separate thread.
> > 
> > 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)?
> 
> Once upon a time Don Knuth had an idea called Literate Programming. He
> had a vision of programs that people could could read for pleasure. I
> think his attempt to implement that idea was a failure but the vision
> lives on.

I think one of the difficulties with the notion of literate
programming has to do with the mental model implicit to the
instantiation of an algorithm.  If one writes a function the
implementation details model one's understanding of the algorithm and
include implicitly the idiosyncracies of the programming process:
variable naming, structure design, as well as the way simple
statements are combined to make a whole function or module.

In C especially, and perhaps most languages, these details make
understanding difficult.  I struggle to understand Ben Pfaff's AVL
tree implementation as a result of his language usage as above, but
ultimately his basic algorithm is and must be the similar to mine.
Clearly this is not enough.  Looking more closely, Ben uses a two
element array to hold left and right pointers, whereas I use explicit
left and right structure elements in the node.  Ben places a balance
factor in the node, and I keep the depth of both left and right
subtrees in each node.  And so on.  The result is two completely
different programs, and each reflects the internalization of
C-language proficiency/understanding in the writer's brain.  Put
another way, programming is the expression of the writer's brain
structure associated with computer programming ability, and even
perhaps the momentary programming environment in which the programmer
works.

To reiterate, the implementation details reflect mental process, and
to understand computer coding is to in some fashion understand the
mental process of the programmer.  This is not a conscious process any
more than reading English is a conscious process.  Ok, reading English
text *may* be a conscious process but much of the time consciousness is
occupied with higher level abstractions presented in the text rather
than with the text itself.  At any rate, there is a great deal of
subtle information associated with human-written code/language and no
easy way to infer it, at least not in a conscious fashion.

Assembler may be something of an equalizer in this vein.  Anecdotal
references in Steven Levy's "Hackers" seems to support this notion.
Due to the fact that assembler is less expressive in the sense of
basic linguistic complexity may make it easier to understand another
writer's code.  Of course when one starts leaning on a macro
preprocessor linguistic complexity begins to increase, perhaps
also increasing the difficulty of modeling the programmer's
programming process, again as above.

I believe the notion of literate programming is valuable but I cannot
say how it ought to be achieved.  I have converged on a programming
style by trial and error which attempts to increase clarity, but I do
not know yet how successful I have been with that goal, and I won't
know until I publish something non-trivial and receive feedback.

> One of the key ideas - it seems to me - is a tree structure of ideas.
> There is one big idea at the top. It is decomposed to into significant
> parts (a dozen or so) and the parts into parts - and so on.
> 
> The comments in the code - it seems to me - are the next to the least 
> step. The last step being the code itself. In a sense writing
>    extern int countOfPeople(void);
> instead of 
>    extern int cntPpl(void);
> is a form of commenting (and a very useful form). 

> Most people these days achieve a tree structure using subroutines. The
> implication IMO is that a subroutine should be fully commented on in the 
> sense of not only what the arguments and returns are but also what the
> subroutine is doing and why it is doing it the way it is. That done
> comments on individual statements should rarely be needed.
> 
> BUT the crux comes when a subroutine is called. Ideally what this
> subroutine will do should be commented on when its called. But that is
> excessive because the needed comment is already there at the subroutine   
> definition. It seems to me that a link is needed here not a comment.
> That is, I would imagine a code document where every mention of a name
> is a link to the definition of that name.  
> 
> And I imagine these links remain in the final published source (an HTML
> document?). I imagine people like me reading applications like novels.

An IDE and documentation standard with that capability is what you want.

> And, of course, I imagine everything is open source.

The notion of "everything is open source" is utopian.  Perhaps it is
necessary from the pure standpoint of computer security, since we know
it is vital to review code to verify that it does what the
documentation says it does and that it does not contain critical
vulnerabilities.  (And of course Ken Thompson's "Reflections on
Trusting Trust" presents a cautionary tale.)

I do not think that open source software will truly come into its own
until it is no longer necessary to work to provide basic sustenance.
The intervening period is proving to be rather interesting in my
opinion.

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.

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