4 ms·

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 wa

by 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...
perl4ever 6y ago
Yeah, but the phrase "only time" somewhat suggests you use "why" as an excuse to comment rarely. You can nonetheless write such a comment for essentially every line. My job description is not "developer" at the moment, so when I was asked to comment my code in order to turn it over to the developers, I looked for some standards. The document I found said, more or less, that you should write comments such that if the code was removed, someone could use the comments to completely reconstruct it. An obvious problem is that you can write about the "why" of anything on a micro or macro level or in between.
- Twisol 6y ago
  > you should write comments such that if the code was removed, someone could use the comments to completely reconstruct it. I understand that this is just a rule of thumb, but it's so far from anything I could expect to happen in reality that it serves as no justification at all. A codebase is a living entity that grows and changes over time. Without sound justification that butresses both when and when not to comment, advice like this can lead to exactly the brittle comments that disillusion people from commenting as a whole. Comments are just a part of a healthy breakfast. You want the code to be as clear as possible, both in the small (algorithmically) and in the large (architecturally). When the code must necessarily fall short, comments must fill that gap -- and only that gap. (Other forms of documentation serve other needs.) It's like unit tests and integration tests: you want as many unit tests as possible, to give you assurance that the pieces from which you assemble your system are correct. Where unit tests cannot speak, other kinds of tests fill the gaps. But if you try to build your test suite out of integration tests, you'll end up pretty miserable.
  - perl4ever 6y ago
    > advice like this can lead to exactly the brittle comments that disillusion people from commenting as a whole As I turn this over in my head, it doesn't sound that convincing because the whole "code should be self-explanatory" ethos seems to me just as susceptible to encouraging bad behavior. Saying something is clear allows you to elevate yourself and blame others if they don't follow. Expecting people to judge their own communication is a definite conflict of interest. Exaggerated commenting requirements as I described are at least a reminder that you should try to err on the other side. Also, for context, the agency I work for is responsible for an accounting system that affects a lot of people and is very much not a "move fast and break things" place. The most exciting thing that happens year after year is reducing the scheduled downtime window(s). Even that obviously must have diminishing returns. The other thing is that in my particular case, the code I wrote is not directly applicable to the accounting system and is written in a different language, so anyone trying to modify it will probably be relatively inexperienced and there is zero chance of anyone being hired to work on it.

by thdrdt 6y ago

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...

perl4ever 6y ago

Yeah, but the phrase "only time" somewhat suggests you use "why" as an excuse to comment rarely. You can nonetheless write such a comment for essentially every line. My job description is not "developer" at the moment, so when I was asked to comment my code in order to turn it over to the developers, I looked for some standards. The document I found said, more or less, that you should write comments such that if the code was removed, someone could use the comments to completely reconstruct it. An obvious problem is that you can write about the "why" of anything on a micro or macro level or in between.

Twisol 6y ago
> you should write comments such that if the code was removed, someone could use the comments to completely reconstruct it. I understand that this is just a rule of thumb, but it's so far from anything I could expect to happen in reality that it serves as no justification at all. A codebase is a living entity that grows and changes over time. Without sound justification that butresses both when and when not to comment, advice like this can lead to exactly the brittle comments that disillusion people from commenting as a whole. Comments are just a part of a healthy breakfast. You want the code to be as clear as possible, both in the small (algorithmically) and in the large (architecturally). When the code must necessarily fall short, comments must fill that gap -- and only that gap. (Other forms of documentation serve other needs.) It's like unit tests and integration tests: you want as many unit tests as possible, to give you assurance that the pieces from which you assemble your system are correct. Where unit tests cannot speak, other kinds of tests fill the gaps. But if you try to build your test suite out of integration tests, you'll end up pretty miserable.
- perl4ever 6y ago
  > advice like this can lead to exactly the brittle comments that disillusion people from commenting as a whole As I turn this over in my head, it doesn't sound that convincing because the whole "code should be self-explanatory" ethos seems to me just as susceptible to encouraging bad behavior. Saying something is clear allows you to elevate yourself and blame others if they don't follow. Expecting people to judge their own communication is a definite conflict of interest. Exaggerated commenting requirements as I described are at least a reminder that you should try to err on the other side. Also, for context, the agency I work for is responsible for an accounting system that affects a lot of people and is very much not a "move fast and break things" place. The most exciting thing that happens year after year is reducing the scheduled downtime window(s). Even that obviously must have diminishing returns. The other thing is that in my particular case, the code I wrote is not directly applicable to the accounting system and is written in a different language, so anyone trying to modify it will probably be relatively inexperienced and there is zero chance of anyone being hired to work on it.