[brown-dragon]

Yep - that's exactly been my experience.

(off-topic) Org mode is really amazing. I've transitioned almost completely from Emacs to Vim over the last few years but I still have Emacs on my dock only because of `org-mode`. I've tried substitutes in vim but nothing really works.

(back on topic) Another advantage of writing comments is coming back to the code becomes so much easier. I can re-read the comments and understand what's going on much faster.

To do this properly I've developed a simple system of 'categories' that allow me to structure the comments properly. I think they works really well. For anyone curious - here's an example in my last weekend project: https://github.com/theproductiveprogrammer/luminate

Check out the comments in the code (`main.js`). I think they make the code much easier to understand and maintain. It's almost an alternative to TDD - Comment Driven Design (CDD!)