C Programming Language 2nd Ed, Exercise 1.9 and 1.12, Solution suggestion.

Discussion in 'C Programming' started by Christos Kokaliaris, Jun 9, 2014.

  1. Christos Kokaliaris

    Jorgen Grahn Guest


    I disagree, but at the same time I think:

    - People sometimes over-comment inside functions (and struct
    definitions), especially if they follow a work pattern where
    they sketch the program flow as comments and then fill in
    the code. Also, such comments sometimes make people spend
    less time on making the code itself self-explanatory: choosing
    good variable names and so on.

    - It's not uncommon to find comments inside the code which
    really should have come in the comment block /before/ it.

    - In the end it's a matter of good judgement. It's a case-by-case
    thing, how to express your intent clearly.
    Seems a bit bogus to me ... if the comments and the code operate in
    different modes, one of them is done wrong! They should both be part
    of a single message to the reader.

    If OTOH you're saying "tuck away useless comments somewhere where I
    can ignore them", then I agree.

    Jorgen Grahn, Jun 14, 2014
    1. Advertisements

  2. Christos Kokaliaris

    Richard Bos Guest

    I'm afraid I just have to continue to disagree. I want my comments
    closest to the code they're about. This means comments about the
    function as a whole go at the top of the function, and functions about
    how a single line (or a couple of lines) do their job go with those
    When I read code, I don't want to spend my time going back and forth
    between the code and the comment. I know some people are now going to
    tell me to write smaller functions, but those people are just being
    silly and fundamentalist, and they know it.

    Richard Bos, Jun 16, 2014
    1. Advertisements

  3. Christos Kokaliaris

    Tim Rentsch Guest

    I agree with all these.
    That is my observation also. Especially deplorable is the
    practice of putting a comment after the final right parenthesis
    surrounding the function's parameters and before the initial
    open brace enclosing the function's body.
    In some sense this is my point - what needs expressing, and at
    what level of detail? How does what needs expressing change
    as a function of time and audience? Presuming we know what
    needs expressing, how should it be expressed so as to both
    improve comprehension and maximize developer effectiveness?
    These questions are not primarily programming questions but
    more in the realm of psychology, and most developers don't
    have the background to form good judgments about how they
    should be answered.
    Here I think is the crux of the matter. There is an unconscious
    assumption that the reader is operating in a single cognitive
    mode, or that there is only one message that needs delivering.
    This assumption is wrong according to studies that have been
    done: people think quite differently when they are approaching
    something for the first time compared to how they think when
    they (mostly) understand what is going on. What message is
    needed is different in the different cases.
    It isn't that the comments are useless. They are useful in one
    cognitive mode, but not useful, or even worse than useless, in
    another cognitive mode. Here is a short example from a piece of
    code posted recently (the posted code originally had no comment):

    unsigned minimum = (RAND_MAX - (n-1)) % n; // 1

    /* Notes:
    * [1] This expression is mathematically equal to (RAND_MAX+1)%n.
    * It is written this way to avoid the possibility of integer
    * overflow. The calculated value gives the smallest value
    * that can be converted so there are equally many values for
    * each possible output, ie, so [ minimum .. RAND_MAX ] is of
    * a size that is a multiple of n.

    If one is seeing this code for the first time, and not familiar
    with the general pattern, the comment is pretty helpful. But for
    developers who already understand the pattern, the comment isn't
    needed - they can read just the single program line and see what
    it is doing essentially instantly. Putting the comment inside
    the function body not only wouldn't help them, it would actually
    slow them down. It's nice to have the comment there for those
    developers who haven't seen this sort of thing before, but it's
    also nice to have it out of the way for those who have. Writing
    comments in the form of footnotes effectively serves the needs of
    both audiences, which could of course be the same audience but at
    different points in their respective experience histories.
    Tim Rentsch, Jun 16, 2014
  4. Christos Kokaliaris

    Tim Rentsch Guest

    Nothing wrong with having an opinion. In this case though the
    opinion is at odds with the results of people who make it their
    job to study such things carefully and thoroughly. For the sake
    of discussion let me agree that this mode works reasonably well
    for you. How do you know that isn't just familiarity and habit,
    and if you had different habits you might find your effectiveness
    improved? I don't mean this question rhetorically - if you were
    approaching the question afresh and trying not to pre-judge the
    different approaches, what would you do to factor earlier habits
    (not just your own but also those of others) out of the results?
    A key point is that most of the time there will be no going back
    and forth because developers familiar with the code don't need to
    read the comments and won't read them. Putting comments inside
    function bodies optimizes the 10% case at the expense of the 90%
    case (or maybe 20/80, but whatever - clearly the balance favors
    the second mode over the first).
    IME functionalizing more - ie, breaking large functions into
    several smaller functional units - goes a long way toward
    reducing the need for commenting, especially if the functions'
    names are well-chosen. So I don't think suggestions along these
    lines are just silly. However I agree that such functionalizing
    won't eliminate the need for comments in all cases - it will
    be reduced, but not completely eliminated.
    Tim Rentsch, Jun 16, 2014
  5. Christos Kokaliaris

    Kaz Kylheku Guest

    You can put small "footnotes" into the code like /* 2 */, which reference
    numbered points in a block comment elsewhere, perhaps above the function.

    I followed this practice for a while more than fifteen years ago;
    it works well.

    It is based on the equivalent practice in text, because the issue is
    essentially the same: we want to concentrate on the main idea, but need to give
    background notes without cluttering it to those who are interested or who
    require them.

    The thing is, if code needs that many footnotes, maybe it's badly written.
    These days I only write an in-line comment when there is something very tricky
    going on (and usually such a thing is written by someone else, and I'm
    add the comment after spending considerable time reverse engineering
    the purpose of the statements which follow, so that someone doesn't have
    to do it again after me.

    E.g. /* This flag is being set here so that the when
    the foo function is invoked in situation q out of function
    bar, it will avoid taking actions x y z. */
    Kaz Kylheku, Jun 16, 2014
  6. Christos Kokaliaris

    Jorgen Grahn Guest

    [comments in code, long snip]
    Perhaps true -- but I think that if more programmers just
    realized/were told that this aspect /exists/, they would do
    significantly better -- without a degree in psychology.

    And now that you mention it: I think a course in technical writing
    (for lack of a better term) should have been part of the CS education
    I had. That would have been more useful than many other things we did.

    I think I'm aware of some of those modes (I use several myself), and
    perhaps unaware of others ... also time and energy is limited. I
    suppose what I do is optimize for people like myself (rather easy),
    and sometimes for people who I know personally, and who will work with
    that code in the future (harder).

    Jorgen Grahn, Jun 16, 2014
    1. Advertisements

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments (here). After that, you can post your question and our members will help you out.