Hacker News new | past | comments | ask | show | jobs | submit login

On a project I am working on, I write all my public interfaces in literate programming style so it can doubles as comprehensive API documentation to put up on GitHub pages or websites or printed for sending to 3rd parties without me having to carefully correlate code and a separate document (they'are already there together.)

On other, more private parts of the code, I just write it normally, with minimal comments.

Another benefits is that, when you change the code, the relevant documentation is right there next to it. I find this minimizes the chance of having an outdated documentation and make it very simple and convenient to update the docs when I update any public interfaces.

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