4 ms·

Comments are often a code smell indicating that the code was written in a hard to understand way. On a top notch code base - the kind that almost nobody works o

Comments are often a code smell indicating that the code was written in a hard to understand way. On a top notch code base - the kind that almost nobody works on - they probably should be sparse and mostly unnecessary. Moreover, when a lot of people are asked to comment they write stuff like "this function does x to y" when the function is named "x_to_y". No shit sherlock comments I call them. I'd always prefer to have good comments, but I've worked on a lot of code bases where no comments wouldn't really have been any worse.

tln 7y ago
Check out the CPython code base sometime, as an example of a top notch code base. Are the comments sparse?
- pytester 7y ago
  Depends on the area of the code you look at, but they can be fairly sparse, yes: https://github.com/python/cpython/blob/master/PC/python_uwp.cpp https://github.com/python/cpython/blob/master/PC/python_uwp.... I'd say that redis is probably a better example of gold standard clean C code, though, and they follow the rule of "don't comment unless it's decidedly non-obvious" pretty assiduously: https://github.com/antirez/redis/blob/unstable/src/ae_epoll.c https://github.com/antirez/redis/blob/unstable/src/ae_epoll....
  - tln 7y ago
    Those two files do have a low ratio of comments. However a large number of files in those code bases have quite a lot more comments... I personally don't think these two code bases have sparse comments, overall, although perhaps it's subjective or my bias is affecting my judgement :) Eg, to me this is well-commented and I wouldn't call it sparse. https://github.com/antirez/redis/blob/unstable/src/latency.c https://github.com/antirez/redis/blob/unstable/src/latency.c
macintux 7y ago
Comments are critical for explaining the code that isn't there. I'm skeptical about "sparse".
- pytester 7y ago
  I'm not sure what you mean. Comments are for explaining code that IS there.
  - replyguy912 7y ago
    comments shouldn't explain code period; they are to clarify intent.
    - pytester 7y ago
      Comments are there to clarify whatever is not easily understood in the code. If that's intent, sure, it's intent that should be commented. It's not always the intent that needs clarification.
  - macintux 7y ago
    "This looks like a good case for a binary tree but it doesn't scale well under load." "We would add support for this motherboard that looks a lot like the one we do support, but it doesn't offer feature X." "We want to add more detailed logs here but we haven't figured out how to cope with the performance hit." Closely related, comments are also useful for explaining why code that looks wrong/poorly optimized/obsolete isn't actually, which is something that the code itself can't explain.

tln 7y ago

Check out the CPython code base sometime, as an example of a top notch code base. Are the comments sparse?

pytester 7y ago
Depends on the area of the code you look at, but they can be fairly sparse, yes: https://github.com/python/cpython/blob/master/PC/python_uwp.cpp https://github.com/python/cpython/blob/master/PC/python_uwp.... I'd say that redis is probably a better example of gold standard clean C code, though, and they follow the rule of "don't comment unless it's decidedly non-obvious" pretty assiduously: https://github.com/antirez/redis/blob/unstable/src/ae_epoll.c https://github.com/antirez/redis/blob/unstable/src/ae_epoll....
- tln 7y ago
  Those two files do have a low ratio of comments. However a large number of files in those code bases have quite a lot more comments... I personally don't think these two code bases have sparse comments, overall, although perhaps it's subjective or my bias is affecting my judgement :) Eg, to me this is well-commented and I wouldn't call it sparse. https://github.com/antirez/redis/blob/unstable/src/latency.c https://github.com/antirez/redis/blob/unstable/src/latency.c

macintux 7y ago

Comments are critical for explaining the code that isn't there. I'm skeptical about "sparse".

pytester 7y ago
I'm not sure what you mean. Comments are for explaining code that IS there.
- replyguy912 7y ago
  comments shouldn't explain code period; they are to clarify intent.
  - pytester 7y ago
    Comments are there to clarify whatever is not easily understood in the code. If that's intent, sure, it's intent that should be commented. It's not always the intent that needs clarification.
- macintux 7y ago
  "This looks like a good case for a binary tree but it doesn't scale well under load." "We would add support for this motherboard that looks a lot like the one we do support, but it doesn't offer feature X." "We want to add more detailed logs here but we haven't figured out how to cope with the performance hit." Closely related, comments are also useful for explaining why code that looks wrong/poorly optimized/obsolete isn't actually, which is something that the code itself can't explain.