Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Hmm... I think you might be missing the concept a bit. What I mean is that there is a lot of documentation that is like this:

  /*
   The phone number
  */
  private static String phoneNumber;
That is considered 'the what', the documentation doesn't explain 'why' the phone number is a field on the class. This might be obvious because the class is called 'Address'... so people will argue that it is self documenting, and it is.

The WTF code is 'the why'...



In something like your example, the what is obvious. But I've seen a lot of code where the what is not at all obvious, and a comment succinctly summing or breaking it down up would help drive the understanding.

The way is useful in addition to that, and often IME far more important than the what. IMO you should document both, as necessary, and that's the hard part/skill. You have to treat it like you won't remember it in 6 months, because in 6 months, you won't. A lot of devs don't do that.

(A fair number of devs won't follow the style guide / idiomatic patterns of a language if there isn't a CI check forcing them to, and will argue to all ends with a human as to why it ought not apply to them, to the great detriment of their code's readability to other experience practitioners of the language. Oddly CI enforcement usually works better, why I don't know.)


> I've seen a lot of code where the what is not at all obvious

So then the question that needs answering is:

"why" is the what not obvious?

Document the "why."


The comment is missing everything useful. If it was public, I'd definitely ask for docs on it:

What is the phone number for? When I read it, is it ready for display as-is or should I be formatting it? Same question when I set it. Can it be null or empty? Does or can the system use this number for anything - such as sending SMS messages?

Being static is a huge red flag, though, and even though it's private I'd still ask. Why is it static? Is this thread-safe (and how)? What context does it get set in, and when can I use it?


Yea, that code was definitely written to throw people off. ;-)


That code isn't WTF. Its completely obvious what it is doing, and the comment is unnecessary.


Read gregmac's comment.




Consider applying for YC's Fall 2025 batch! Applications are open till Aug 4

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: