6 ms·

So many times this. "Clear code shouldn't need comments" - clear code can make it easy to see what but it can never say why. Let me know what corner cases you

by ris 6y ago

So many times this. "Clear code shouldn't need comments" - clear code can make it easy to see what but it can never say why. Let me know what corner cases you thought about when you wrote this. "The comments are in the commit messages" - almost nobody ever goes looking for them there, they're effectively invisible from `git blame` when they remove lines, people rarely make fine grained enough commits to be able to target specific lines or blocks sufficiently with context. "Nobody ever updates comments, so they're always out of date" - don't hire such people. It is an crucial task resolving the meaning of comments to make sure everything still makes cohesive sense. Neglecting to do this will often lead to commits that don't quite grok any subtleties of the original design. Don't make the reader of the code do the job of trying to piece together the scattered history of 5 different people's intentions. Of course, it's also useful to try to keep comments as close to the code in question as possible so that references which need updating are obvious to see.

sanderjd 6y ago
> almost nobody ever goes looking for them there I've seen this claim a number of times and it's always so odd to me. One of my most common activities each day - certainly more common than the activity of writing new code - is reading the commit history for different files. It's always surprising to me to hear that this is an uncommon thing to do. Edit to add: But I also think comments and documentation of all kinds are good. I don't advocate good commit messages instead of comments, but rather in addition to comments. The more documentation the better.
- Braxton_Hicks 6y ago
  Agreed. I think the "nobody ever goes looking for them" case is common for code bases where people are not writing good useful commit messages.
- phendrenad2 6y ago
  Commit messages are much harder to get to for a given line of code than a comment would be.
  - shepherdjerred 6y ago
    Not if you use a nice IDE: https://www.jetbrains.com/help/idea/investigate-changes.html#annotate https://www.jetbrains.com/help/idea/investigate-changes.html...
    - rpdillon 6y ago
      Or even just Emacs. http://www.gnu.org/software/emacs/manual/html_node/emacs/Old-Revisions.html http://www.gnu.org/software/emacs/manual/html_node/emacs/Old...
  - sanderjd 6y ago
    I actually find file and directory level history useful more often than the line-level annotate/blame history that seems to get all the attention. I do find line level history useful as well, I'm just saying less often. At the directory level, I look at the history of commit messages to get a sense for how the module(s) under that directory have evolved over time. At the file level, I look at the history of commit messages and often dig into the associated diff in order to see how the API and/or implementation have evolved. I'll often follow the file-level diff to the full commit to see what the entire change entailed. This gives me tons of context on the what and the why of a codebase's evolution, and it's all aided by good commit messages. Line level blame/annotate is sometimes useful when I'm trying to trace how some particular implementation came to be, but it is easy to lose the thread across deletions and renames, which I find file and directory level history to be much more resilient to.
- aflag 6y ago
  Which tool do you use to view commit messages and revisions for each file? I think one of the reasons this is uncommon is due to lack of tooling (or wide-spread knowledge of them). I'd really like to be able to easily see all the previous commits that affected a specific line while I'm editing code. But I usually have to resort to interacting with git, rather than having something popping up on my screen (I use pycharm and vim regularly).
  - kevinschumacher 6y ago
    Not the person you were replying to, but in PyCharm: - right click on the line number, click Annotate; this gives you the commit date and author in the gutter - hover over the date/author name; this gives you the commit hash and message - click on the hash itself in the popover; this shows the git commit graph on the Version Control tab - right click on the date/author name, click Annotate Revision; this opens up the version committed then, with its git blame in the gutter.
    - aflag 6y ago
      That's nice, and setting the options to detect movements really improves it. It'd be nice to see the commit message, rather than the author, without the need to hovering, though.
  - nfRfqX5n 6y ago
    I use gitlens for vscode
  - nemetroid 6y ago
    I use tig, which is a terminal UI. The "blame" view has a shortcut to jump to the commit before the one that changed a given line. This makes it easy to quickly dig backwards through the history of a file.
  - recursive 6y ago
    Visual Studio has this. It's called "Annotate".
pronoiac 6y ago
> "The comments are in the commit messages" - almost nobody ever goes looking for them there Consider it another tool in the toolbox. I've gone spelunking through git history to decipher the reasoning of something still in use, though comments had been deleted and no one had documented it before me.
- zimpenfish 6y ago
  This works iff there are good commit messages. In my experience, people who don't document their code tend not to bother with good commit messages either.
cjfd 6y ago
Clear code needs some comments. Not many, though. If you write a numerical algorithm it probably needs an explanation or a reference to where it came from or something like that. Generally, one needs a comment when it is difficult to figure out why something was written that way. In many cases comments are not needed. I perhaps write a comment once every ten files or maybe even less but then it tends to be a rather long comment because the thing explained is very non-obvious. The kind of comment that I hate seeing is when somebody feels the need to tell me what methods are constructors or similar such nonsense.
phlakaton 6y ago
> people rarely make fine grained enough commits to be able to target specific lines or blocks Take your own advice then: don't hire such people. Why would you insist on maintaining documentation and not maintaining a reasonable change log in your commits, if knowing "why" is important to you? (I make the advice tongue-in-cheek btw. Better to educate and lift developers up wherever you can than just freeze them out. Not everyone has the experience with these things that we do.) There's not a one-size-fits-all solution here. Different orgs handle their code history different ways, but having tasted the power Git gives you over certain other VCSes to make the commit log really useful as a record of change, and having taken advantage of that feature several times myself, I wouldn't want to go back. This follows another comment I just made on the topic: https://news.ycombinator.com/item?id=23743973 https://news.ycombinator.com/item?id=23743973
codegladiator 6y ago
> "Clear code shouldn't need comments" That's like saying articles don't need summary.
- unoti 6y ago
  Agreed; or like saying "You don't need a map; you can clearly see where this road leads if you follow it far enough."
tigershark 6y ago
Clear code and clear tests shows both the what and the why. With the additional advantage that they can’t diverge and be out of sync like the comments because otherwise the tests will fail. Comments should be used to explain something unexpected. Commenting each line of code is a recipe for disaster.
thdrdt 6y ago
The only time I place comments is exactly this: to explain why. Today I just had this example. I placed a little sleep in a loop. But there is absolutely no way to know why it is there. So I inserted a comment to explain the loop is DOSing a server by constantly requesting it and the sleep will reduce the load on that server. Those comments are not only for others but also for yourself. Even weeks from now it is easy to lose track on why you did things the way you did. Comments on why are very helpful.
- ChrisMarshallNY 6y ago
  That's exactly what I do. Why is a lot more important that what. Here's an example I use (Verbatim from here[0]): - Why Vs. What I’ve come to realize that the most important inline documentation concerns WHY we are doing something; not WHAT we are doing. For example, no one wants to read “// Set the value of b to 3,” for a line of code that looks like let b = 3. That’s just dumb. let b = 3 // Set the value of b to 3 However, they may want to know “// Set the value of b to the number of iterations we'll be making.” let b = 3 // Set the value of b to the number of iterations we'll be making - [0] https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c8014 https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c...
  - ekimekim 6y ago
    Or perhaps even better: let iterations = 3 // We need to iterate 3 times for the value to stabilize
    - thdrdt 6y ago
      Yes, I think your example is better because "// Set the value of b to the number of iterations we'll be making" is almost the same as "/ Set the value of b to 3" when the code explains that `b` is used for the iterations.
      - ChrisMarshallNY 6y ago
        I actually take it forward a bit more in that article, to where clear naming eliminates the need for a comment at all: - With a good name, we could probably do away with the comment entirely: let numberOfIterations = 3 - It’s a fairly exhaustive article (but kind of a long read). Documentation is an important topic. https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c8014 https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c...
clairity 6y ago
yes, comments should be considered code too, but for humans, so later coders (including your later self) can effectively simulate (not but necessarily replicate) the prior code-writing process(es). it's as critical as the code for machines. which is to say, the comments should be kept concise and current too.
Ma8ee 6y ago
A lot of comments can (and should) be replaced with good naming. Sometimes the only reason to introduce a variable or function is to name something. The advantage is that it is harder to not read a name than it is to not read a comment, and it is more obviously a bug when we try to set a variable, or make a function calculate, something not agreeing with its name.
deleted 6y ago
[deleted]
namelosw 6y ago
> Let me know what corner cases you thought about when you wrote this. We actually rarely use comments in code. The best way to reflect the corner cases are tests. It is the comments codified. > but it can never say why Usually people don't need to know why on small piece of code unless it's a high-level stuff. For high-level stuff we have architecture decision records (ADR) which records the motivations and situations. But we also keep it very short or people would never read those. > "Nobody ever updates comments, so they're always out of date" - don't hire such people. That's a really high standards. It's almost like "We have bugs", "Well, then don't hire people writing bugs"... There are many ways of breaking comments. For example, someone changed module A, then the properties on module B changed because of A. If it's a test it will reflects on CI, but if it's a comment there's almost no way for people to realize that.
gkfasdfasdf 6y ago
I've found that questions during a code review make excellent fodder for comments. I.e. if someone has a question (not necessarily an issue) about a piece of code, it's a good bet someone might have a similar question when reading the code later.

by ris 6y ago

sanderjd 6y ago

> almost nobody ever goes looking for them there I've seen this claim a number of times and it's always so odd to me. One of my most common activities each day - certainly more common than the activity of writing new code - is reading the commit history for different files. It's always surprising to me to hear that this is an uncommon thing to do. Edit to add: But I also think comments and documentation of all kinds are good. I don't advocate good commit messages instead of comments, but rather in addition to comments. The more documentation the better.

Braxton_Hicks 6y ago
Agreed. I think the "nobody ever goes looking for them" case is common for code bases where people are not writing good useful commit messages.
phendrenad2 6y ago
Commit messages are much harder to get to for a given line of code than a comment would be.
- shepherdjerred 6y ago
  Not if you use a nice IDE: https://www.jetbrains.com/help/idea/investigate-changes.html#annotate https://www.jetbrains.com/help/idea/investigate-changes.html...
  - rpdillon 6y ago
    Or even just Emacs. http://www.gnu.org/software/emacs/manual/html_node/emacs/Old-Revisions.html http://www.gnu.org/software/emacs/manual/html_node/emacs/Old...
- sanderjd 6y ago
  I actually find file and directory level history useful more often than the line-level annotate/blame history that seems to get all the attention. I do find line level history useful as well, I'm just saying less often. At the directory level, I look at the history of commit messages to get a sense for how the module(s) under that directory have evolved over time. At the file level, I look at the history of commit messages and often dig into the associated diff in order to see how the API and/or implementation have evolved. I'll often follow the file-level diff to the full commit to see what the entire change entailed. This gives me tons of context on the what and the why of a codebase's evolution, and it's all aided by good commit messages. Line level blame/annotate is sometimes useful when I'm trying to trace how some particular implementation came to be, but it is easy to lose the thread across deletions and renames, which I find file and directory level history to be much more resilient to.
aflag 6y ago
Which tool do you use to view commit messages and revisions for each file? I think one of the reasons this is uncommon is due to lack of tooling (or wide-spread knowledge of them). I'd really like to be able to easily see all the previous commits that affected a specific line while I'm editing code. But I usually have to resort to interacting with git, rather than having something popping up on my screen (I use pycharm and vim regularly).
- kevinschumacher 6y ago
  Not the person you were replying to, but in PyCharm: - right click on the line number, click Annotate; this gives you the commit date and author in the gutter - hover over the date/author name; this gives you the commit hash and message - click on the hash itself in the popover; this shows the git commit graph on the Version Control tab - right click on the date/author name, click Annotate Revision; this opens up the version committed then, with its git blame in the gutter.
  - aflag 6y ago
    That's nice, and setting the options to detect movements really improves it. It'd be nice to see the commit message, rather than the author, without the need to hovering, though.
- nfRfqX5n 6y ago
  I use gitlens for vscode
- nemetroid 6y ago
  I use tig, which is a terminal UI. The "blame" view has a shortcut to jump to the commit before the one that changed a given line. This makes it easy to quickly dig backwards through the history of a file.
- recursive 6y ago
  Visual Studio has this. It's called "Annotate".

pronoiac 6y ago

> "The comments are in the commit messages" - almost nobody ever goes looking for them there Consider it another tool in the toolbox. I've gone spelunking through git history to decipher the reasoning of something still in use, though comments had been deleted and no one had documented it before me.

zimpenfish 6y ago
This works iff there are good commit messages. In my experience, people who don't document their code tend not to bother with good commit messages either.

cjfd 6y ago

Clear code needs some comments. Not many, though. If you write a numerical algorithm it probably needs an explanation or a reference to where it came from or something like that. Generally, one needs a comment when it is difficult to figure out why something was written that way. In many cases comments are not needed. I perhaps write a comment once every ten files or maybe even less but then it tends to be a rather long comment because the thing explained is very non-obvious. The kind of comment that I hate seeing is when somebody feels the need to tell me what methods are constructors or similar such nonsense.

phlakaton 6y ago

> people rarely make fine grained enough commits to be able to target specific lines or blocks Take your own advice then: don't hire such people. Why would you insist on maintaining documentation and not maintaining a reasonable change log in your commits, if knowing "why" is important to you? (I make the advice tongue-in-cheek btw. Better to educate and lift developers up wherever you can than just freeze them out. Not everyone has the experience with these things that we do.) There's not a one-size-fits-all solution here. Different orgs handle their code history different ways, but having tasted the power Git gives you over certain other VCSes to make the commit log really useful as a record of change, and having taken advantage of that feature several times myself, I wouldn't want to go back. This follows another comment I just made on the topic: https://news.ycombinator.com/item?id=23743973 https://news.ycombinator.com/item?id=23743973

codegladiator 6y ago

> "Clear code shouldn't need comments" That's like saying articles don't need summary.

unoti 6y ago
Agreed; or like saying "You don't need a map; you can clearly see where this road leads if you follow it far enough."

tigershark 6y ago

Clear code and clear tests shows both the what and the why. With the additional advantage that they can’t diverge and be out of sync like the comments because otherwise the tests will fail. Comments should be used to explain something unexpected. Commenting each line of code is a recipe for disaster.

thdrdt 6y ago

The only time I place comments is exactly this: to explain why. Today I just had this example. I placed a little sleep in a loop. But there is absolutely no way to know why it is there. So I inserted a comment to explain the loop is DOSing a server by constantly requesting it and the sleep will reduce the load on that server. Those comments are not only for others but also for yourself. Even weeks from now it is easy to lose track on why you did things the way you did. Comments on why are very helpful.

ChrisMarshallNY 6y ago
That's exactly what I do. Why is a lot more important that what. Here's an example I use (Verbatim from here[0]): - Why Vs. What I’ve come to realize that the most important inline documentation concerns WHY we are doing something; not WHAT we are doing. For example, no one wants to read “// Set the value of b to 3,” for a line of code that looks like let b = 3. That’s just dumb. let b = 3 // Set the value of b to 3 However, they may want to know “// Set the value of b to the number of iterations we'll be making.” let b = 3 // Set the value of b to the number of iterations we'll be making - [0] https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c8014 https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c...
- ekimekim 6y ago
  Or perhaps even better: let iterations = 3 // We need to iterate 3 times for the value to stabilize
  - thdrdt 6y ago
    Yes, I think your example is better because "// Set the value of b to the number of iterations we'll be making" is almost the same as "/ Set the value of b to 3" when the code explains that `b` is used for the iterations.
    - ChrisMarshallNY 6y ago
      I actually take it forward a bit more in that article, to where clear naming eliminates the need for a comment at all: - With a good name, we could probably do away with the comment entirely: let numberOfIterations = 3 - It’s a fairly exhaustive article (but kind of a long read). Documentation is an important topic. https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c8014 https://medium.com/chrismarshallny/leaving-a-legacy-1c2ddb0c...

clairity 6y ago

yes, comments should be considered code too, but for humans, so later coders (including your later self) can effectively simulate (not but necessarily replicate) the prior code-writing process(es). it's as critical as the code for machines. which is to say, the comments should be kept concise and current too.

Ma8ee 6y ago

A lot of comments can (and should) be replaced with good naming. Sometimes the only reason to introduce a variable or function is to name something. The advantage is that it is harder to not read a name than it is to not read a comment, and it is more obviously a bug when we try to set a variable, or make a function calculate, something not agreeing with its name.

deleted 6y ago

[deleted]

namelosw 6y ago

> Let me know what corner cases you thought about when you wrote this. We actually rarely use comments in code. The best way to reflect the corner cases are tests. It is the comments codified. > but it can never say why Usually people don't need to know why on small piece of code unless it's a high-level stuff. For high-level stuff we have architecture decision records (ADR) which records the motivations and situations. But we also keep it very short or people would never read those. > "Nobody ever updates comments, so they're always out of date" - don't hire such people. That's a really high standards. It's almost like "We have bugs", "Well, then don't hire people writing bugs"... There are many ways of breaking comments. For example, someone changed module A, then the properties on module B changed because of A. If it's a test it will reflects on CI, but if it's a comment there's almost no way for people to realize that.

gkfasdfasdf 6y ago

I've found that questions during a code review make excellent fodder for comments. I.e. if someone has a question (not necessarily an issue) about a piece of code, it's a good bet someone might have a similar question when reading the code later.