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

> Don't write two things, one of which executes and the other explains it; write an explanation which also executes.

I can see how your code can explain the `what' and `how'. How are you going to answer `why' and even more important `why not'?

By `why not', I mean, a short description of why some reasonable alternative choices were not made. Eg why we use algorithm A and not B and not C.



If the choice is testable, you can write a test case for it. B and C don't work because they break the test case; A is required.

If the choice isn't testable in any way, it's not worth commenting on.

In general, in many programs we can find algorithms that could be replaced by better ones (such that no test cases break). There is no need to explain why that is the case; all the various possible reasons for that are obvious, and it doesn't matter which ones of them are true.


> If the choice isn't testable in any way, it's not worth commenting on.

Choices about architecture are hard to test in a unit-test sense, but are worth commenting on.




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

Search: