4 ms·

I agree 100% with the section on documenting your system and code. It's sobering to consider how many HN posts about software development contain comments to th

by kmoser 2y ago

I agree 100% with the section on documenting your system and code. It's sobering to consider how many HN posts about software development contain comments to the contrary, indicating that documentation (and heavily commenting your code) is useless. It seems the longer you've been developing software, and/or the bigger the project, the more you become a fan of documentation.

OtomotO 2y ago
Documentation can be utterly useless, if taken to the extreme. Like e.g. in Java it was common to have a comment on a simple (!) setter, telling you "this sets X" No shit, captain obvious! Never would have guessed that. I like a combination of "literate programming" (in a light form at least), that leads to readable, self explanatory code that's still fast and well (not prematurely) optimized. But reading docs about the most trivial things: Brrr!
- kmoser 2y ago
  I'll gladly deal with a few (or even many) useless "this sets X" comments if they come along with helpful comments for other non-trivial methods.
- medo-bear 2y ago
  > Like e.g. in Java it was common to have a comment on a simple (!) setter, telling you "this sets X" Given the prevelance of mutating functions in Java this is welcome
  - OtomotO 2y ago
    No, it's not. Because it doesn't add anything. Just document if something is mutating and what it mutates. Or simply name your functions accordingly. Like of your setter is doing a HTTP call, maybe name it so that it's obvious.
- elric 2y ago
  > Like e.g. in Java it was common to have a comment on a simple (!) setter, telling you "this sets X" This has never been common in any sensible environment. Only on projects with project leads who had zero clue about anything, and with silly catch-all rules such as "EVERY METHOD MUST BE DOCUMENTED!". This predictably leads to shitty documentation. /** * Sets foo to <code>foo</code> * @param foo new foo value */ public void setFoo(int foo) { this.foo = foo; } No one sensible does this. Some IDEs might auto generate this garbage. In which case that should be disabled.
  - OtomotO 2y ago
    Wholeheartedly agree, but there is a lot of non sensible software out there ;-)
  - rcxdude 2y ago
    It's probably the largest fraction of javadoc by volume I've seen.
    - elric 2y ago
      I'm sorry to hear that you've been plagued by shitty codebases. Have you considered trying to improve them? Or maybe try looking for greener pastures.
elric 2y ago
My previous customer insisted that documentation (Javadoc in particular) was Bad and should be Avoided. Because "code should be self documenting". It's such a stupid fallacy. I could not convince them to even add the bare minimum of class-level documentation (explaining what the purpose is of a given class and how it fits into the bigger picture). This is all fine and well today, when you're working on that code base. But three years down the line when you have to go back to fix a bug ... good luck remembering how the ConfabulatingFooService relates to the ChristmasLights system.

by kmoser 2y ago

OtomotO 2y ago

Documentation can be utterly useless, if taken to the extreme. Like e.g. in Java it was common to have a comment on a simple (!) setter, telling you "this sets X" No shit, captain obvious! Never would have guessed that. I like a combination of "literate programming" (in a light form at least), that leads to readable, self explanatory code that's still fast and well (not prematurely) optimized. But reading docs about the most trivial things: Brrr!

kmoser 2y ago
I'll gladly deal with a few (or even many) useless "this sets X" comments if they come along with helpful comments for other non-trivial methods.
medo-bear 2y ago
> Like e.g. in Java it was common to have a comment on a simple (!) setter, telling you "this sets X" Given the prevelance of mutating functions in Java this is welcome
- OtomotO 2y ago
  No, it's not. Because it doesn't add anything. Just document if something is mutating and what it mutates. Or simply name your functions accordingly. Like of your setter is doing a HTTP call, maybe name it so that it's obvious.
elric 2y ago
> Like e.g. in Java it was common to have a comment on a simple (!) setter, telling you "this sets X" This has never been common in any sensible environment. Only on projects with project leads who had zero clue about anything, and with silly catch-all rules such as "EVERY METHOD MUST BE DOCUMENTED!". This predictably leads to shitty documentation. /** * Sets foo to <code>foo</code> * @param foo new foo value */ public void setFoo(int foo) { this.foo = foo; } No one sensible does this. Some IDEs might auto generate this garbage. In which case that should be disabled.
- OtomotO 2y ago
  Wholeheartedly agree, but there is a lot of non sensible software out there ;-)
- rcxdude 2y ago
  It's probably the largest fraction of javadoc by volume I've seen.
  - elric 2y ago
    I'm sorry to hear that you've been plagued by shitty codebases. Have you considered trying to improve them? Or maybe try looking for greener pastures.

elric 2y ago

My previous customer insisted that documentation (Javadoc in particular) was Bad and should be Avoided. Because "code should be self documenting". It's such a stupid fallacy. I could not convince them to even add the bare minimum of class-level documentation (explaining what the purpose is of a given class and how it fits into the bigger picture). This is all fine and well today, when you're working on that code base. But three years down the line when you have to go back to fix a bug ... good luck remembering how the ConfabulatingFooService relates to the ChristmasLights system.