7 ms·

Question for experienced C programmers (I'm not one). The comments for remove_list_entry strike me as fluff, only suitable for a didactic piece. Would you find

Question for experienced C programmers (I'm not one). The comments for remove_list_entry strike me as fluff, only suitable for a didactic piece. Would you find the comments in the second version helpful, or should they also be removed? Edit: let me lay my cards on the table. If the comments really are necessary, it doesn’t seem elegant. I’m pro-comments, but that’s because not all code can be readable and elegant all the time.

identity0 6y ago
The top pattern is extremely common so comments are somewhat unnecessary since everyone would know what you're doing. In the second one, comments would be less necessary with a type annotation and perhaps a better name. Maybe "next_ptr" instead of "indirect"---all pointers are indirection, so that name is redundant. But the comments are necessary, to me at least.
- eperdew 6y ago
  All pointers are pointers too, so I don't see much of a difference between "indirect" and "next_ptr", other than the "next" part. In similar situations at my job, I've drawn a small ASCII diagram in the comments, and named the variable something like "splice_point", with a corresponding label in the diagram.
  - identity0 6y ago
    Well "next_ptr" is also a bad name, I agree, but I'm trying to name it something that indicates "this is a pointer to the 'next' pointer in the linked list".
    - scns 6y ago
      How about next_node?
valtism 6y ago
The comments certainly don't detract from the code in my opinion. They may not be _helpful_ per se to an experienced developer, but there may be a chance that a more inexperienced developer will read this code in the future, and it could benefit them.
tooltower 6y ago
While I wouldn't write this much comment, I can see a use for this: navigation. If I'm trying to quickly find the part I want to modify, the comments do help me skim through quickly and zoom in on the part I care about. It's the same reason a blog post is often broken up into section headings. Without the comments, I'd have to spend a few extra seconds trying to map chunks of the code with my mental model of how linked lists work. Those few seconds can interrupt the flow of work. So I'll disagree with the notion that only illegible or unreadable code needs comment.
emerged 6y ago
For my tastes there is way too much whitespace and I usually only use multi-line comments to describe the high level algorithm for a full function. I prefer to pepper single-line comments which describe the sequence of events in a human-readable way. I've been C/C++ for about 25 years.
- pacaro 6y ago
  My taste is that function level comments describe the "what" and inline comments describe the "why". So at a function level the comments is giving a highlevel description to the reader as to the functionality contained, and at the line level comments exist only to say describe the programmers intentionality, why it was implemented this way rather than some other way. I have generally found (there are always exceptions) that if you find yourself needing "what" comments within a function you should be considering breaking it into smaller pieces. I've been being paid to write c/c++ for about 25 years
  - emerged 6y ago
    The main takeaway here might be that two 25 year veterans both make function level and line level comments. The particulars are somewhat of a matter of flavor preference :)
    - ghusbands 6y ago
      That is not a particularly useful takeaway, especially when one of them is pointing out that particular comments in a function are problematic. The particulars matter.
munchbunny 6y ago
I would expect to see barely any comments in the "in production" version, other than a comment like: // indirect is either &head or &(node->next), so *indirect is equivalent to "next node" Someone who knows their C should be able to figure it out in a few minutes by just reading the code.

identity0 6y ago

The top pattern is extremely common so comments are somewhat unnecessary since everyone would know what you're doing. In the second one, comments would be less necessary with a type annotation and perhaps a better name. Maybe "next_ptr" instead of "indirect"---all pointers are indirection, so that name is redundant. But the comments are necessary, to me at least.

eperdew 6y ago
All pointers are pointers too, so I don't see much of a difference between "indirect" and "next_ptr", other than the "next" part. In similar situations at my job, I've drawn a small ASCII diagram in the comments, and named the variable something like "splice_point", with a corresponding label in the diagram.
- identity0 6y ago
  Well "next_ptr" is also a bad name, I agree, but I'm trying to name it something that indicates "this is a pointer to the 'next' pointer in the linked list".
  - scns 6y ago
    How about next_node?

valtism 6y ago

The comments certainly don't detract from the code in my opinion. They may not be _helpful_ per se to an experienced developer, but there may be a chance that a more inexperienced developer will read this code in the future, and it could benefit them.

tooltower 6y ago

While I wouldn't write this much comment, I can see a use for this: navigation. If I'm trying to quickly find the part I want to modify, the comments do help me skim through quickly and zoom in on the part I care about. It's the same reason a blog post is often broken up into section headings. Without the comments, I'd have to spend a few extra seconds trying to map chunks of the code with my mental model of how linked lists work. Those few seconds can interrupt the flow of work. So I'll disagree with the notion that only illegible or unreadable code needs comment.

emerged 6y ago

For my tastes there is way too much whitespace and I usually only use multi-line comments to describe the high level algorithm for a full function. I prefer to pepper single-line comments which describe the sequence of events in a human-readable way. I've been C/C++ for about 25 years.

pacaro 6y ago
My taste is that function level comments describe the "what" and inline comments describe the "why". So at a function level the comments is giving a highlevel description to the reader as to the functionality contained, and at the line level comments exist only to say describe the programmers intentionality, why it was implemented this way rather than some other way. I have generally found (there are always exceptions) that if you find yourself needing "what" comments within a function you should be considering breaking it into smaller pieces. I've been being paid to write c/c++ for about 25 years
- emerged 6y ago
  The main takeaway here might be that two 25 year veterans both make function level and line level comments. The particulars are somewhat of a matter of flavor preference :)
  - ghusbands 6y ago
    That is not a particularly useful takeaway, especially when one of them is pointing out that particular comments in a function are problematic. The particulars matter.

munchbunny 6y ago

I would expect to see barely any comments in the "in production" version, other than a comment like: // indirect is either &head or &(node->next), so *indirect is equivalent to "next node" Someone who knows their C should be able to figure it out in a few minutes by just reading the code.