3 ms·

> But if you are creating something like a library of basic math functions I would rather read your code than your docs. Talking about software specifically: t

by brabel 2y ago

> But if you are creating something like a library of basic math functions I would rather read your code than your docs. Talking about software specifically: this is the exact wrong way to do it. A programming interface should be easy to use and "self-documented" to some extent (by, e.g. using the type system as much as possible to make bad states unrepresentable), but only very simple interfaces are usable that way. For most real-world interfaces, there's just no way you can encode all the "rules" in the type system and the names. You absolutely need to document how your interface works in general, what each part is used for and expected to do, special cases and so on that are just impossible to know otherwise. Now, if you just read the implementation instead (and notice that you would need to read all implementations, most interfaces are likely implemented in many different ways) you're not coding against an interface at all. You're assuming the implementation is the interface. You're ignoring what the implementer intended to be private and subject to change. Don't do that.

jajko 2y ago
Yeah thats a horrible approach that creates massive additional costs down the line, usually not author's problem anymore though. Can't really put finger on it precisely, maybe its too large ego (my time is too valuable for some pesky documentation for idiots, I am a superstar! No you're not, you are at vee best a brilliant junior...). Or maybe lack of basic empathy, surprisingly high number of humans can over time learn how to work in society but any novel situation requiring some empathy they handle like mammoth ina porcelaine shop. Or something else in similar vein. That was quite shocking, entering adulthood and discovering vast number of folks have such issues
- dingnuts 2y ago
  I used to write a lot of comments and I don't much anymore. Usually a long comment is a smell. If the way something works isn't obvious and must be explained, it can probably be better designed. Code changes and then comments have to be updated, and often aren't. If they aren't just wrong, the context is often so changed that they aren't useful. You wind up reading the legacy code anyway, and you and the author both wasted time with comments. My team is smart and competent. I need them to read the code to make sure their changes are safe, anyway. They do not need their hands held. They don't need me to waste time writing comments that will soon be outdated, or that explain something I should have designed better. Finally, management doesn't apply an OKR to intangible code metrics like internal documentation. Should they? I don't know, but it's their code, not mine, so I'll write it to the standard they apply. These are the reasons you have to work in code that is poorly documented. It has nothing to do with a lack of empathy -- if I were to allow my employer to extract extra value from me by using my empathy for my teammates as a lever that would be exploitation. If I spend more time on documentation -- which the employer doesn't value -- instead of functionality, I'll be punished at review time for wasting time on worthless things. Maybe you should stop letting your company manipulate you into doing more work than they're paying for. If they value internal documentation, they'll create an OKR or KPI or whatever to make sure you're paid to do it. Otherwise it's unpaid labor for a for profit corporation. I'm not doing that. Are you?
  - deleted 2y ago
    [deleted]
  - IgorPartola 2y ago
    There are situations where a long comment is warranted. Sometimes you have to drain the septic tank and it’s a nasty process. Better do it once in a contained environment wearing gloves and a mask. Document why this code sucks. Explain what it does and why. But in most cases explaining what your code does is like explaining a joke: if you have to explain it, it’s probably not very good.
- danielheath 2y ago
  It’s not that I’ll assume the internals are not going to change. I just don’t trust the docs to be accurate anymore. The implementation contains an accurate description of what it actually does. I still read the docs… with a grain of salt.
  - jajko 2y ago
    Man, sometimes I would give some gold for some documentation, even 10 years old. Half-irrelevant, doesn't matter. At least something. Sometimes, I don't have even that. That's what drowning in complexity looks like since there are some many question marks and often nobody anymore to answer them. Even stellar code just tells me whats going on. Doesn't tell anything about why its happening, what consequences does it have in other systems, what are the overall constraints of this domain etc. I agree generally too long comments aren't best, or even just non-flexible rules. But denser the logic is, the more spread its across multiple systems and environments, the more info the better. And to be changing some dense code and completely ignoring comments just next to it describing them... that's just rude to be polite. Shows who is a team player and who isn't. Trust me, if you want to make friends and have some respect in some long term team, this is one sure way how to do it.

by brabel 2y ago

jajko 2y ago

Yeah thats a horrible approach that creates massive additional costs down the line, usually not author's problem anymore though. Can't really put finger on it precisely, maybe its too large ego (my time is too valuable for some pesky documentation for idiots, I am a superstar! No you're not, you are at vee best a brilliant junior...). Or maybe lack of basic empathy, surprisingly high number of humans can over time learn how to work in society but any novel situation requiring some empathy they handle like mammoth ina porcelaine shop. Or something else in similar vein. That was quite shocking, entering adulthood and discovering vast number of folks have such issues

dingnuts 2y ago
I used to write a lot of comments and I don't much anymore. Usually a long comment is a smell. If the way something works isn't obvious and must be explained, it can probably be better designed. Code changes and then comments have to be updated, and often aren't. If they aren't just wrong, the context is often so changed that they aren't useful. You wind up reading the legacy code anyway, and you and the author both wasted time with comments. My team is smart and competent. I need them to read the code to make sure their changes are safe, anyway. They do not need their hands held. They don't need me to waste time writing comments that will soon be outdated, or that explain something I should have designed better. Finally, management doesn't apply an OKR to intangible code metrics like internal documentation. Should they? I don't know, but it's their code, not mine, so I'll write it to the standard they apply. These are the reasons you have to work in code that is poorly documented. It has nothing to do with a lack of empathy -- if I were to allow my employer to extract extra value from me by using my empathy for my teammates as a lever that would be exploitation. If I spend more time on documentation -- which the employer doesn't value -- instead of functionality, I'll be punished at review time for wasting time on worthless things. Maybe you should stop letting your company manipulate you into doing more work than they're paying for. If they value internal documentation, they'll create an OKR or KPI or whatever to make sure you're paid to do it. Otherwise it's unpaid labor for a for profit corporation. I'm not doing that. Are you?
- deleted 2y ago
  [deleted]
- IgorPartola 2y ago
  There are situations where a long comment is warranted. Sometimes you have to drain the septic tank and it’s a nasty process. Better do it once in a contained environment wearing gloves and a mask. Document why this code sucks. Explain what it does and why. But in most cases explaining what your code does is like explaining a joke: if you have to explain it, it’s probably not very good.
danielheath 2y ago
It’s not that I’ll assume the internals are not going to change. I just don’t trust the docs to be accurate anymore. The implementation contains an accurate description of what it actually does. I still read the docs… with a grain of salt.
- jajko 2y ago
  Man, sometimes I would give some gold for some documentation, even 10 years old. Half-irrelevant, doesn't matter. At least something. Sometimes, I don't have even that. That's what drowning in complexity looks like since there are some many question marks and often nobody anymore to answer them. Even stellar code just tells me whats going on. Doesn't tell anything about why its happening, what consequences does it have in other systems, what are the overall constraints of this domain etc. I agree generally too long comments aren't best, or even just non-flexible rules. But denser the logic is, the more spread its across multiple systems and environments, the more info the better. And to be changing some dense code and completely ignoring comments just next to it describing them... that's just rude to be polite. Shows who is a team player and who isn't. Trust me, if you want to make friends and have some respect in some long term team, this is one sure way how to do it.