14 ms·

I have mixed feelings about this. I think it depends on the project you are working on. If your codebase can be packed into a few hundred lines of code, with no

I have mixed feelings about this. I think it depends on the project you are working on. If your codebase can be packed into a few hundred lines of code, with nothing fancy or complicated and no code is being injected from elsewhere, then the author is absolutely right. Documenting what a function or a method does should be sufficient and imo you should do that in all cases, just for the sake of making it easier for new developers to jump into the project if they prefer using some fancy IDE. However if your codebase is composed of several million lines of code(like a lot of the ones I work on), things change. Using readable names is a perfect general advice but eventually you end up with complex logic, which is not necessarily the result of some developer who just wanted to get a task out of their way but could be as well a result of "business needs this by Monday, 3 weeks ago" or simply some mind boggling edge case which needs to be handled. In which case, adding some inline comment with an explanation as to why something is there and ideally a link to your ticketing system can be a life savior. I'm far not a fan of things like: // Increment counter by 1. counter++; You should never do that unless you are studying programming and you have been required to explain every line of code along the way(though I don't know why a professor would ever want that, certainly no one ever asked me to do stuff like that).

galacticdessert 6y ago
I think your point is in line with the article. Comment WHY you are doing something, rather than commenting HOW. And, if you are in a hurry and the logic/naming is somewhat unclear, leave a comment to clarify. In a future refactor, the logic might be made more clear and comments removed.
davethedevguy 6y ago
I agree entirely. As far as code that handles bizarre edge-cases, I tried to cover that in "Comments that explain why". Perhaps I missed the mark a little, but I think I was intending to agree with the point you made. "Often, it’s because I’ve profiled it and found it to be significantly faster, or because it catches an edge-case that a more intuitive method of doing the same thing might not .. Comments like this get to stay." To your point about "business needs this by Monday, 3 weeks ago". Under those circumstances, I write comments to explain my rushed code all the time. In my personal case though, I'd consider this to be "Comments as an excuse not to refactor". It might be a good excuse (maybe the business need trumps readability in the short-term), but I know it's still an excuse and not something I should be doing all the time. I'm trying to get better at going back and refactoring those things later.
echelon 6y ago
> Documenting what a function or a method does should be sufficient and imo you should do that in all cases, just for the sake of making it easier for new developers to jump into the project if they prefer using some fancy IDE. Document nothing until you have to do something weird and unexpected. An example might be: // NB: We're downsampling to 22khz because we found that the // multi-speaker model chokes on higher sample rates. source = downsample(source, 22000) Or: // We don't perform internal retries here because our clients // handle that themselves when we respond with a 429. retryCount = 0 Or: /* Firefox renders this mistakenly, and overflows the element. We opted to add padding to account for this difference. See BUG-4282 for more details. */ padding: 0 0 3px; This strategy captures all of the things that you'll forget, but leaves nothing that might go stale. In essence, only the things of value that couldn't be intuited from the code itself. Do not leave any other types of comments! Ever! Not even method docs. (The only exception being if you're writing a library and want to generate a documentation website). You'll find that you start writing code that is like poetry. Structured, naturally intuitive, and easy for others to read. You'll become a better programmer, and your code base will improve dramatically. Comments, of course, will never go out of date.
- axegon_ 6y ago
  > Do not leave any other types of comments! Ever! Not even method docs. Have you ever looked at a very large project(blue whale as I'd like to call them)? In 10 years time, 90% of the people who have worked on it initially will be gone from the company (or stopped contributing if it's an open source project). You are making everyone else's life a nightmare. To my mind the one project that got it bang on is postgres. It is by no means a library and the community's approach is perfect. Open up any of the source code files at random and you'll see what I'm on about. Just scrolling through the code and comments once will be enough for you to figure out exactly what is there and why.
  - echelon 6y ago
    > Have you ever looked at a very large project > You are making everyone else's life a nightmare. I work on code touched by tens of thousands of other engineers. In my experience, code without comments is typically structured, easy to read, and does exactly what is written. Code painted top to bottom with comments tends to be muddied, confusing, and more junior in nature. The shape of solutions is common. You're not reinventing the wheel with every new project. Engineers are familiar with the design patterns, frameworks, and algorithms you use, so you don't need to force a context switch to point them out. You can use the symbols themselves as a form of documentation. Instead of having an entire algorithm inline, individual queries or processing steps might be put into their own self-documenting methods: verifyMarkdown(article_rating: &Rating) upsertRating(article_rating: &Rating, author: &User, transaction: &Transactor) publish(article_rating: &Rating, transaction: &Transactor) enqueueSubscriberNotifications(author: &User) Small pieces of code might not require a functions to wrap them, but by naming small units of behavior, you can communicate your algorithm step by step without comments. This is only one type of communication technique you can use. There are bountiful ways to improve your clarity. I apologize if my examples are obtuse. It's late.

galacticdessert 6y ago

I think your point is in line with the article. Comment WHY you are doing something, rather than commenting HOW. And, if you are in a hurry and the logic/naming is somewhat unclear, leave a comment to clarify. In a future refactor, the logic might be made more clear and comments removed.

davethedevguy 6y ago

I agree entirely. As far as code that handles bizarre edge-cases, I tried to cover that in "Comments that explain why". Perhaps I missed the mark a little, but I think I was intending to agree with the point you made. "Often, it’s because I’ve profiled it and found it to be significantly faster, or because it catches an edge-case that a more intuitive method of doing the same thing might not .. Comments like this get to stay." To your point about "business needs this by Monday, 3 weeks ago". Under those circumstances, I write comments to explain my rushed code all the time. In my personal case though, I'd consider this to be "Comments as an excuse not to refactor". It might be a good excuse (maybe the business need trumps readability in the short-term), but I know it's still an excuse and not something I should be doing all the time. I'm trying to get better at going back and refactoring those things later.

echelon 6y ago

> Documenting what a function or a method does should be sufficient and imo you should do that in all cases, just for the sake of making it easier for new developers to jump into the project if they prefer using some fancy IDE. Document nothing until you have to do something weird and unexpected. An example might be: // NB: We're downsampling to 22khz because we found that the // multi-speaker model chokes on higher sample rates. source = downsample(source, 22000) Or: // We don't perform internal retries here because our clients // handle that themselves when we respond with a 429. retryCount = 0 Or: /* Firefox renders this mistakenly, and overflows the element. We opted to add padding to account for this difference. See BUG-4282 for more details. */ padding: 0 0 3px; This strategy captures all of the things that you'll forget, but leaves nothing that might go stale. In essence, only the things of value that couldn't be intuited from the code itself. Do not leave any other types of comments! Ever! Not even method docs. (The only exception being if you're writing a library and want to generate a documentation website). You'll find that you start writing code that is like poetry. Structured, naturally intuitive, and easy for others to read. You'll become a better programmer, and your code base will improve dramatically. Comments, of course, will never go out of date.

axegon_ 6y ago
> Do not leave any other types of comments! Ever! Not even method docs. Have you ever looked at a very large project(blue whale as I'd like to call them)? In 10 years time, 90% of the people who have worked on it initially will be gone from the company (or stopped contributing if it's an open source project). You are making everyone else's life a nightmare. To my mind the one project that got it bang on is postgres. It is by no means a library and the community's approach is perfect. Open up any of the source code files at random and you'll see what I'm on about. Just scrolling through the code and comments once will be enough for you to figure out exactly what is there and why.
- echelon 6y ago
  > Have you ever looked at a very large project > You are making everyone else's life a nightmare. I work on code touched by tens of thousands of other engineers. In my experience, code without comments is typically structured, easy to read, and does exactly what is written. Code painted top to bottom with comments tends to be muddied, confusing, and more junior in nature. The shape of solutions is common. You're not reinventing the wheel with every new project. Engineers are familiar with the design patterns, frameworks, and algorithms you use, so you don't need to force a context switch to point them out. You can use the symbols themselves as a form of documentation. Instead of having an entire algorithm inline, individual queries or processing steps might be put into their own self-documenting methods: verifyMarkdown(article_rating: &Rating) upsertRating(article_rating: &Rating, author: &User, transaction: &Transactor) publish(article_rating: &Rating, transaction: &Transactor) enqueueSubscriberNotifications(author: &User) Small pieces of code might not require a functions to wrap them, but by naming small units of behavior, you can communicate your algorithm step by step without comments. This is only one type of communication technique you can use. There are bountiful ways to improve your clarity. I apologize if my examples are obtuse. It's late.