3 ms·

I don't care about comments, I care about unit tests and I need to run trough code with debugger. If code is testable I can run piece of code in isolation and u

by ozim 8y ago

I don't care about comments, I care about unit tests and I need to run trough code with debugger. If code is testable I can run piece of code in isolation and understand how it works. Most of the time people do comments: a = 4 //assign value 4 to a Of course that is exaggeration but usually they restate obvious things and think it is good comment. Also I don't trust comments, I have to see commit history, and if I see there was piece of code changed where comments are, without stepping through and debugging I don't trust code is doing what comment is saying. I do not know how other people are writing code, but I have to run code locally, ideally in unit test or click through in the interface with test data. Maybe others just can run code in their heads and account for what is written in comments. But unfortunately I am not human compiler/runtime/processor.

crazygringo 8y ago
> Most of the time people do comments: a = 4 //assign value 4 to a When I see people arguing against comments, I see this strawman again and again and again. In my multiple decades of programming I have never seen anybody write a blatantly redundant comment like that. It's not "most of the time" that people comment like that, in my experience it's never. Programmers have a job to do, and in my experience generally do not waste their time using comments to "restate obvious things and think it's a good comment". Rather, they comment when necessary to explain the why, or to provide a concise 2-sentence description that would be too long for a function name but lets you skip reading the next 30 lines of code which would take much longer. I really wish people would stop using this strawman of "most comments are redundant/obvious anyways, therefore don't comment". I mean, maybe you personally did have the terrible luck to work with a codebase that was actually like that... but I personally have never seen it.
- ergothus 8y ago
  > but I personally have never seen it. I have. That said, I think we are on the same position on the issue. When I've seen such comments, it's when someone that didn't understand the value if comments is responding to a request to ask them. Thus is not necessarily because they are being deliberately obtuse, but because they never really experienced helpful comments. To me, 90% of the time a good comment wont say what's happening, instead it will say WHY it is happening. If good coding practised makes the code itself clear, good coding practice makes the context the code is written in clear. But for those new, and/or those too use to a particular codebase or just never exposed to good comments, they wont get it, and when asked to do one (either as a general request or in a code review) the strawman is what you get (usually not as ridiculous as this example, but equally useless). I see it as a cycle when learn to code: first we find comments useless so we skip them where we can. Then thus becomes normal, so we are used to seeing no or only useless comments. Then one day we look at code that we know we were confused on before but have forgotten why. On the N-th time of this, we leave the one line comment that says the secret. On the N plus one-th time, we read that comment and are enlightened. We then spend years trying to figure out the magic behind a useful and a useless comment, and arguing with those who think only useless comments exist.
- ozim 8y ago
  So you are working with experienced people. It looks I don't have such luck, I have to look at lots of junior code. Juniors think that they should write comments and then they waste time writing epic descriptions of trivial things. They waste time writing whole story of creating simple piece of code in one commit message. They waste time deliberating if tabs are better than spaces.
  - mcny 8y ago
    My personal anecdotal evidence is that they are not junior in the organizational chart. I'm just a contractor. They are a part of the company. Who am I to tell them they shouldn't comment "what" and "how" after every line they write? This job made me hate inline comments. If I were to ever create a new language, I'd insist in there being no way to write comments in the same line as executable code.
- DanFeldman 8y ago
  I've seen those types of comments everywhere, but only with "junior" devs, or more likely, from people without a CS background. Often these folks haven't had much exposure to clean production code or dug through open source libraries. They're trying to be helpful and document but don't really have the mental models of what needs to be commented or not. This is easy to train away though, through showing examples of what I think needs commenting, or straight up deleting comments during code reviews and by adding Docstrings instead of inline comments. To be clear, I agree with you about how comments should be used.
- BeetleB 8y ago
  >In my multiple decades of programming I have never seen anybody write a blatantly redundant comment like that. It's not "most of the time" that people comment like that, in my experience it's never. While I share your dislike for this counterargument, it's certainly not never for me. Not even close. In my last job, I was dealing with code that had been in development for 15-20 years. We started a project to clean up the codebase. I would randomly browse people's commits. A fair amount of cleanup involved removing exactly those types of comments. >Programmers have a job to do, and in my experience generally do not waste their time using comments to "restate obvious things and think it's a good comment". Try working on a code base developed by engineers who are not trained in programming.
- jiveturkey 8y ago
  multiple decades and you haven’t seen this? i’m floored. i see it all the time.
- thegeekpirate 8y ago
  > In my multiple decades of programming I have never seen anybody write a blatantly redundant comment like that. You're simply insanely lucky!
- wycy 8y ago
  Agreed, I’ve never seen this sort of super redundant comments either in any real production code. I’ve only seen it in a small number of times in a handful of scripts written by interns.
karmelapple 8y ago
Tests are what matter to me and my team, too. Tests = requirements. As another commenter pointed out, we use comments for why. Sometimes the commit history can help this, but a well-placed comment can shrink that effort. I get a feeling we may not pass OP’s litmus test, but I’d be curious if we would. We use the term self-documenting code, but that’s primarily because our tests are part of our code, and those tests are indeed our primary documentation.
roblabla 8y ago
The code explains how. The comments explains why. Why does this function have to take that lock? Why is that algorithm chosen? What invariants are required to be upheld (which is a form of "why?"). Good code comments are important. Good unit tests are important too. But both are necessary.
u801e 8y ago
> Also I don't trust comments, I have to see commit history That only works if the commit message is informative. A commit message that says "updated tests" is just as informative as a comment that says "assign value to a" (following your code comment example). Commit messages are as, if not more important, than code comments (given VCS tools like git blame that can associate code changes with a comment explaining what was done and why).
- ozim 8y ago
  I don't look at commit messages either, I look at diffs of file I am working on.

by ozim 8y ago

crazygringo 8y ago

> Most of the time people do comments: a = 4 //assign value 4 to a When I see people arguing against comments, I see this strawman again and again and again. In my multiple decades of programming I have never seen anybody write a blatantly redundant comment like that. It's not "most of the time" that people comment like that, in my experience it's never. Programmers have a job to do, and in my experience generally do not waste their time using comments to "restate obvious things and think it's a good comment". Rather, they comment when necessary to explain the why, or to provide a concise 2-sentence description that would be too long for a function name but lets you skip reading the next 30 lines of code which would take much longer. I really wish people would stop using this strawman of "most comments are redundant/obvious anyways, therefore don't comment". I mean, maybe you personally did have the terrible luck to work with a codebase that was actually like that... but I personally have never seen it.

ergothus 8y ago
> but I personally have never seen it. I have. That said, I think we are on the same position on the issue. When I've seen such comments, it's when someone that didn't understand the value if comments is responding to a request to ask them. Thus is not necessarily because they are being deliberately obtuse, but because they never really experienced helpful comments. To me, 90% of the time a good comment wont say what's happening, instead it will say WHY it is happening. If good coding practised makes the code itself clear, good coding practice makes the context the code is written in clear. But for those new, and/or those too use to a particular codebase or just never exposed to good comments, they wont get it, and when asked to do one (either as a general request or in a code review) the strawman is what you get (usually not as ridiculous as this example, but equally useless). I see it as a cycle when learn to code: first we find comments useless so we skip them where we can. Then thus becomes normal, so we are used to seeing no or only useless comments. Then one day we look at code that we know we were confused on before but have forgotten why. On the N-th time of this, we leave the one line comment that says the secret. On the N plus one-th time, we read that comment and are enlightened. We then spend years trying to figure out the magic behind a useful and a useless comment, and arguing with those who think only useless comments exist.
ozim 8y ago
So you are working with experienced people. It looks I don't have such luck, I have to look at lots of junior code. Juniors think that they should write comments and then they waste time writing epic descriptions of trivial things. They waste time writing whole story of creating simple piece of code in one commit message. They waste time deliberating if tabs are better than spaces.
- mcny 8y ago
  My personal anecdotal evidence is that they are not junior in the organizational chart. I'm just a contractor. They are a part of the company. Who am I to tell them they shouldn't comment "what" and "how" after every line they write? This job made me hate inline comments. If I were to ever create a new language, I'd insist in there being no way to write comments in the same line as executable code.
DanFeldman 8y ago
I've seen those types of comments everywhere, but only with "junior" devs, or more likely, from people without a CS background. Often these folks haven't had much exposure to clean production code or dug through open source libraries. They're trying to be helpful and document but don't really have the mental models of what needs to be commented or not. This is easy to train away though, through showing examples of what I think needs commenting, or straight up deleting comments during code reviews and by adding Docstrings instead of inline comments. To be clear, I agree with you about how comments should be used.
BeetleB 8y ago
>In my multiple decades of programming I have never seen anybody write a blatantly redundant comment like that. It's not "most of the time" that people comment like that, in my experience it's never. While I share your dislike for this counterargument, it's certainly not never for me. Not even close. In my last job, I was dealing with code that had been in development for 15-20 years. We started a project to clean up the codebase. I would randomly browse people's commits. A fair amount of cleanup involved removing exactly those types of comments. >Programmers have a job to do, and in my experience generally do not waste their time using comments to "restate obvious things and think it's a good comment". Try working on a code base developed by engineers who are not trained in programming.
jiveturkey 8y ago
multiple decades and you haven’t seen this? i’m floored. i see it all the time.
thegeekpirate 8y ago
> In my multiple decades of programming I have never seen anybody write a blatantly redundant comment like that. You're simply insanely lucky!
wycy 8y ago
Agreed, I’ve never seen this sort of super redundant comments either in any real production code. I’ve only seen it in a small number of times in a handful of scripts written by interns.

karmelapple 8y ago

Tests are what matter to me and my team, too. Tests = requirements. As another commenter pointed out, we use comments for why. Sometimes the commit history can help this, but a well-placed comment can shrink that effort. I get a feeling we may not pass OP’s litmus test, but I’d be curious if we would. We use the term self-documenting code, but that’s primarily because our tests are part of our code, and those tests are indeed our primary documentation.

roblabla 8y ago

The code explains how. The comments explains why. Why does this function have to take that lock? Why is that algorithm chosen? What invariants are required to be upheld (which is a form of "why?"). Good code comments are important. Good unit tests are important too. But both are necessary.

u801e 8y ago

> Also I don't trust comments, I have to see commit history That only works if the commit message is informative. A commit message that says "updated tests" is just as informative as a comment that says "assign value to a" (following your code comment example). Commit messages are as, if not more important, than code comments (given VCS tools like git blame that can associate code changes with a comment explaining what was done and why).

ozim 8y ago
I don't look at commit messages either, I look at diffs of file I am working on.