3 ms·

> Why did the API endpoint change? ... This stuff all feels better suited for a commit message. Conversely if I found all this in code I'd delete it. I'm an a

> Why did the API endpoint change? ... This stuff all feels better suited for a commit message. Conversely if I found all this in code I'd delete it. I'm an almost never comment person (I use them when things are weird or inconsistent, but otherwise view them as noise) but I've been persuaded by John Ousterhout that code cannot adequately describe abstractions, and you need comments to fill in the gap. Similarly with variable names, if you don't know i is index, please don't try working on this code. I get some code is a soup of inscrutable variable names and flow control to the degree it looks decompiled, but that's a higher level composition problem, not a "use more nouns" problem.

ehnto 4y ago
I also almost never comment code architecture and logic, but code is usually solving some business problem and documenting that in code is just not always reasonable or even possible. Also bugfixes and compat related naming in live software gets you things like fixForObserverOverrideBugIn364 For me it's more about not wasting people's time. Names are opportunities to divulge minor contextual information that you spent time figuring out, and it would be going backwards to then compress that into shortened names. i for index is fine, but if you have nested loops or multiple loops it gets annoying.
- camgunz 4y ago
  Oh yeah totally get it. I feel like our area of agreement is that whenever you're writing code, you should be writing it to be read and understood, not simply executed. Whether that's through naming, comments, docs, structure, etc. An example of a comment I'd value is something like a "why bother" at the top of a file doing a lot of in-depth algorithmic work, like a note accompanying a Chesterton's Fence. It makes some sense (though I quibble with this all the time) to design things so as to be as understandable as possible, and then only start optimizing when necessary, and when that happens it's useful to put a "this is pretty complicated, but it cuts CPU time down by 30%. [here](link) are the tests, and [here](link) is the naive equivalent implementation".

ehnto 4y ago

I also almost never comment code architecture and logic, but code is usually solving some business problem and documenting that in code is just not always reasonable or even possible. Also bugfixes and compat related naming in live software gets you things like fixForObserverOverrideBugIn364 For me it's more about not wasting people's time. Names are opportunities to divulge minor contextual information that you spent time figuring out, and it would be going backwards to then compress that into shortened names. i for index is fine, but if you have nested loops or multiple loops it gets annoying.

camgunz 4y ago
Oh yeah totally get it. I feel like our area of agreement is that whenever you're writing code, you should be writing it to be read and understood, not simply executed. Whether that's through naming, comments, docs, structure, etc. An example of a comment I'd value is something like a "why bother" at the top of a file doing a lot of in-depth algorithmic work, like a note accompanying a Chesterton's Fence. It makes some sense (though I quibble with this all the time) to design things so as to be as understandable as possible, and then only start optimizing when necessary, and when that happens it's useful to put a "this is pretty complicated, but it cuts CPU time down by 30%. [here](link) are the tests, and [here](link) is the naive equivalent implementation".