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

I agree wholeheartedly. The best software documentation is the an actually well written software module + test that explains its functionality.


Let's not forget about comments.

A well written piece of code will only tell you what it does, a good suite of tests will teach you how to use it, but only natural language documentation - be it in comments or separate documents - will explain to you why the code exists in the first place, and why it looks the way it does.

(As for "self-documenting code", unless a lot of your functions contain the word "because" in their name, the code isn't really self-documenting.)


in summary: what -> naming convention why -> comments how -> tests

I wish this was more commonly shared and understood




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

Search: