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

The WHY is also very useful in comments, especially in business/UI/glue code where special cases abound.


I would say the why might be more important than the what a lot of the time


Came here to comment along those lines.

The WHY often will be elaborate enough that it deserves a design document that includes things like: who is the owner of those requisites, what is the rationale behind them, who are the stakehilders who signed off, what interactions it has other components, what alternative designs were considered, etc.


This. And in particular if there are multiple ways to do it, and you had to choose a particular way for a reason.

Comments should explain the decision process (if one was necessary) that lead to this variant. Because if there's no comment explaining it, the next developer looking at it will say "oh, but it's much simpler if I just do it that way", and will run into trouble because he didn't realize the pitfalls.




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

Search: