News for hackers. Stuff that matters.
Re:Design Docs at Google by TeMPOraL on Wednesday July 22, 2020 @06:18PM (#23922219)
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.)

Re:Design Docs at Google by mkoubaa on Wednesday July 22, 2020 @10:46PM (#23923697)
in summary: what -> naming convention why -> comments how -> tests

I wish this was more commonly shared and understood