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 3 of 3 — ← Prev page 1 2 [3]

#60554

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.

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.

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

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

#60732

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.

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

#60752

On Wednesday, April 22, 2015 at 6:47:41 AM UTC-7, Steve Thompson wrote:
> On Mon, Apr 20, 2015 at 11:37:14AM -0700, David Kleinecke wrote:
> 
> > 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.
 
Consider security.

If I am serious about security I will make a rigid separation between code
and data and will reinstall ALL my code from some external source at a 
regular interval. That is all well and good except how do I update my code?

I will want to be sure that the code I have is the code I want. This means
I want a human-readable form of the code. The easiest way to get that is to
compile/assemble the code from its source. That means I only need to trust
the compiler/assembler and a few loaders. I imagine these can be fixed 
throughout the life time of my machine - but replacing them in a trusted
way probably can be done. 

So if I want to add a new application I read the source code until I am
satisfied there are no problems, use my compiler/assembler and add my new
code to the collection on the external medium. Note the external. The real
code is not accessible to the computer (except for a few moments).

I don't know that anybody actually does this. In my experience nobody -
even so-called security experts - really take security seriously. But it
seems to me a genuine need.

In this scheme executables are never distributed. I can create "code" on
the fly if I want to with an interpreter and I still have not addressed the
problem of hostile scripts. Hence not a silver bullet - but a step forward.   

 

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

#60681

My thanks to everyone for their responses.  I expect I will have
some individual followups later but first let me offer some
general ideas for your further consideration and/or rebuttal.

Comments used for commenting broadly fall into one of two
categories - interface comments or implementation comments.
Roughly speaking, interface comments describe /what/ things do
(usually at the API level), and implementation comments describe
/how/ something is done (or how something works, which is similar
but not exactly the same).  These two categories are the most
important.

Comments are also used for purposes other than commenting:  for
example, as markers, as reminders, or to give revision history.
The point of such uses is to support the development process in
some way.  There are different opinions about how useful these
practices are, but I think most would agree they are largely
orthogonal to matters of readability.  Does anyone think
otherwise (and if so, how or why)?

Also, the point of interface comments is not really about
readability.  In a way, it's the opposite - good interface
comments allow one to not read the actual source providing those
interfaces (ie, function bodies, etc) at all.  So even though
interface comments provide some value, they do not bear directly
on matters of readability.  (Obviously they can help indirectly
for /clients/ of the interface, but that is not our primary
concern here.)

ISTM no one said much about the contents of implementation
comments.  There were two main pieces of general advice
(hopefully I haven't forgotten any), namely, don't write in
comments what can be expressed in code (some examples were given
for that), and write in clear and gramatically correct language.
The best part was the examples - I think details like this are
where the meat is.  That doesn't mean only specific examples
necessarily, but the "specific" part is important.  The rest
mostly didn't seem very useful, either because I take it for
granted (maybe I shouldn't!) or because it seems like an
"exhortation" - eg, saying writing should be clear doesn't help
because that's what we're trying to find out, is what makes
something clear.  (And I should go back and be more explicit
about these, but I hope the general principle is apparent.)
What I'm looking for is guidelines - they can be coarse and
approximate, but they should be mostly objective.

Speaking for myself, implementation comments may be devided into
four levels granularity:  (a) module, (b) function, (c) block, or
(d) element.  (The "block" level just means a group of related
statements or declarations, not related to the notion of a block
in C syntax.)  A "module" usually corresponds to one .c file,
although many-to-one and one-to-many scenarios are both possible.
The order of listing is also IMO the order of importance - if
forced to choose, I would rather have a good module-level comment
than all the others put together.  Similarly function-level
comments are more important than block-level comments, etc.
Of course in particular instances there may be counterexamples
to this statement, but the general rule holds nearly always.

A module-level comment is best written as one or more prose
paragraphs (perhaps with indented nested elements showing short
code fragments or pseudo-code, if necessary), appearing at the
top of a module, which is to say before any non-comment lines
(blank lines don't count) of the file (or sub-files) in question.
The paragraphs should be readable as ordinary text, with all
the usual style advice given for writing in general.

Function-level comments have more variety.  They might take the
form of just a pseudo-code equivalent.  They might take the form
of just a sequence of sentences (or short paragraphs) meant to
be read indivdually, not as connected.  They might take the form
of a prose paragraph (or probably two at the most).  The key
attribute of function-level comments is that they address the
function defintion as a whole - even if parts of a function
comment concerns specific sub-parts, the point of the comment
is to describe how these parts fit into the overall function
context.  Funtion-level comments are best written just after
the function to which they pertain.

Block-level comments are probably the most common type (ie, of
the four types of implementation comments I listed) in C code.
Let me skip these for a moment and talk about element-level
comments.

Element-level comemnts apply to the most basic entities that make
up a program, normally single statements or single declarators
(note:  declarators as distinct from declarations).  The key
properties that go along with element-level comments is that they
are (primarily) local in what they describe, and should not be
too "deep".  What I mean by the second part is that assimilating
the content should require little or no conscioius thought.  Here
I will give an example (and no arguments please if someone thinks
the comment is not appropriate, the point is to illustrate the
property, not to judge the comment):

    int (*f[10])( int, int ) = {    // array of pointers to function

The purpose of the comment here is evident:  we want to make it
easier to translate from C declaration syntax to a form that a
reader (either ourself or another reader) might say in their
head.  The point of the example is that the comment is providing
suplementary material, or perhaps a memory aid, that can be
absorbed mostly subconsciously, without having to activate
consscious thought processes.  This property does not hold for
the three other types of implementation comments.  ALso, because
of the locality relationship, element-level comments are best
written at the end of a line (that being the same line on which
the element being commented appears, if possible).

Getting back to block-level comments...  In many cases comments
that look like block-level comments are really disguised
function-level comments (parts of a larger pseudo-code writing),
but interspersed through a function body.  When I said earlier
that this type is the most common in C, that was a little bit
misleading, because many (most?) comments that look like
block-level comments apply to a larger context than just the
nearby block (again, this is meant in the sense of group of
related statments, not in the way that C uses the term block).
An example of a true block-level comment might be "this loop
maintains as invariant the predicate ...".  In a sense the key
distinction between block-level comments and function-level
comments is to what degree they apply only locally - if it needs
a larger context to make sense, it's a function-level comment,
but if it needs only the context of the particular block to make
sense, it's a block-level comment.  Why does that matter?  The
main thing there shouldn't be any question in the reader's mind
about the scope to which a comment is meant to apply;  as long as
that is clear, the labels don't really matter.

IMO block-level comments should be written in a mamner similar to
function-level comments, that is, following the function body
(and perhaps with a footnote marker in the body itself, to show
which block the comment is associated with).  My reasoning behind
this conclusion is simple - when code and comments are written
interspersed with each other, I find it greatly slows down my
reading, and also comprehension, compared to the two appearing
separately.  Moreover this holds both when reading for the first
time (when most of the reading focuses on comments, not code) or
later after I am more familiar with what's going on (when most of
the reading focuses on code, not comments).  So it's pretty much
a win-win (for reading) to separate the two.  The exception to
that principle is element-level comments, which do not have this
property precisely because they are written in a way (ie, off to
the right hand side) that does not interfere with the flow of
reading just code, and because they do not require a change of
cognitive mode to assimilate (ie, due to the subconscious-only
property mentioned earlier).

And now I look forward to your responses, questions, and
criticisms.  :)

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

#60686

On 2015-04-21, Tim Rentsch <txr@alumni.caltech.edu> wrote:
>
> Function-level comments have more variety.  They might take the
> form of just a pseudo-code equivalent.  They might take the form
> of just a sequence of sentences (or short paragraphs) meant to
> be read indivdually, not as connected.  They might take the form
> of a prose paragraph (or probably two at the most).  The key
> attribute of function-level comments is that they address the
> function defintion as a whole - even if parts of a function
> comment concerns specific sub-parts, the point of the comment
> is to describe how these parts fit into the overall function
> context.  Funtion-level comments are best written just after
> the function to which they pertain.
>

Initially the last line of this paragraph really captured my
attention, which is not to say the entire post wasn't interesting but I
really had to think about what you were saying and again when a similar
thought appears further in your post. 

I don't believe I've ever seen this done and don't know how I'd react to
it and can accept that it may make sense in a long function. Is this
what you mean (ignoring the fact the comments are really short and
unnecessary)?

int some_arcane_network_stream_parser (int fd, char* (*stream_reader)(int)) {
	for (char* str = stream_reader (fd); strcmp (str, "end") != 0; str = stream_reader (fd)) { //^
		if (strcmp (str, "int") == 0) { //^^
			int_stuff_doer ();
		}
		... //lots of code redacted 

		free (str); //^^^^^
	}

	/*
	* ^ Clever use of the for statement required to foo the bar
	*   as well as for other arcane reasons I'll explain here
	*   ...
	* ^^ Protocol clevernet requires declaration of all types.
	*    Once the type has been read we can call the appropriate
	*    doer fucntion ...
	* ^^^^^ stream_reader alocates memory - free when done but don't
	*       close the fd since the internet will break.
	*/
}


-- 
http://www.softsprocket.com

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

#60972

Greg Martin <greg.at.softsprocket@dot.com> writes:

> On 2015-04-21, Tim Rentsch <txr@alumni.caltech.edu> wrote:
>
>> Function-level comments have more variety.  They might take the
>> form of just a pseudo-code equivalent.  They might take the form
>> of just a sequence of sentences (or short paragraphs) meant to
>> be read indivdually, not as connected.  They might take the form
>> of a prose paragraph (or probably two at the most).  The key
>> attribute of function-level comments is that they address the
>> function defintion as a whole - even if parts of a function
>> comment concerns specific sub-parts, the point of the comment
>> is to describe how these parts fit into the overall function
>> context.  Funtion-level comments are best written just after
>> the function to which they pertain.
>
> Initially the last line of this paragraph really captured my
> attention, which is not to say the entire post wasn't interesting
> but I really had to think about what you were saying and again
> when a similar thought appears further in your post.
>
> I don't believe I've ever seen this done and don't know how I'd
> react to it and can accept that it may make sense in a long
> function.  Is this what you mean (ignoring the fact the comments
> are really short and unnecessary)?
>
> [minor editing, primarily for line length]
> int some_arcane_network_stream_parser (int fd, char* (*stream_reader)(int)) {
>     for (char* str;  str = stream_reader (fd), strcmp (str, "end"); ) { //^
>         if (strcmp (str, "int") == 0) { //^^
>             int_stuff_doer ();
>         }
>         ... //lots of code redacted 
>
>         free (str); //^^^^^
>     }
>
>     /*
>     * ^ Clever use of the for statement required to foo the bar
>     *   as well as for other arcane reasons I'll explain here
>     *   ...
>     * ^^ Protocol clevernet requires declaration of all types.
>     *    Once the type has been read we can call the appropriate
>     *    doer fucntion ...
>     * ^^^^^ stream_reader alocates memory - free when done but don't
>     *       close the fd since the internet will break.
>     */
> }

Basically yes.  (Minor point:  your example concerns block-level
comments rather than function-level comments, but I presume that's
what you want to ask about.)  Your example differs from what I was
hoping to convey in two minor but I believe significant ways.
One, I did say "just after the function", and I meant that - after
the closing brace that ends the function definition.  (I can say
more about why if you're interested, let me skip over that for
now.)  Two, usually the "markers" would be written like footnote
references, eg

        ...
        if (strcmp (str, "int") == 0) {                           // 2
        ...
    }
    /* Notes:
     *  ...
     * [2] Protocol clevernet requires declaration of all types. (etc)
     *
     *  ...
     */

The point of this organization is to support two distinct
cognitive modes when reading the code.  These correspond
approximately to reading a piece of code for the first
time, and later reading when you mostly know what's going
on.

When I read code that I haven't seen before or perhaps haven't
seen for a fair while, oftentimes I can't just read the code
right away - I need to take some time.  When this happens,
typically I briefly look over the whole function definition to
get a sense of its structure, then look in depth at the notes,
perhaps referring back to the function body for context every now
and then.  At some point in going through the notes I "get it",
and then I can read the function definition without looking at
the notes anymore, because I've internalized what they have to
say, and I don't need to look at them anymore.

When I read code that I just wrote or that I've read recently
enough so how it works is mostly still "swapped in", then I just
jump right in and don't read the notes at all, or occasionally
read one here or there just selectively.  In this mode not
only do I (mostly) not need the notes, having them present where
my attention is focused would be a distraction and interfere
with reading the code proper.  Putting all the notes out of
the way after the function definition helps avoid those
negative effects.

When writing code we naturally want to help people who haven't
ever seen the code before;  this corresponds to the first, "slow"
reading mode.  Most development activity, however, happens in the
second, "fast" or "encoded" reading mode, where comments are
mostly not only not helpful but actually deleterious to what we're
trying to get done.  Psychological studies have verified these
results:  when working in unfamiliar territory, people want to see
"the long explanation" for a while, until they get comfortable
with what's going on;  but after they do get comfortable, they
generally prefer working exclusively in the "encoded" mode.
The "footnote comment" scheme described supports both modes,
but importantly also observes the distinction between them and
recognizes the higher weight the second mode deserves.

(I'm sure this is obvious, but the last few paragraphs give a
more complete explanation of the brief "cognitive modes" remark
I made in the earlier thread that precipitated this one.  So
I hope this helps people who were wondering about that earlier.)

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

#60973

What makes code readable?

Python

Bye,
  Skybuck :)

[toc] | [prev] | [standalone]

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

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

csiph-web