Hacker News Reader

Comment by kmoser | Hacker News Reader

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.

View on HN

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.

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!

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

Wholeheartedly agree, but there is a lot of non sensible software out there ;-)

It's probably the largest fraction of javadoc by volume I've seen.

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.

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.

> 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

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.

Reply on news.ycombinator.com