These days I tend to think that code should contain guides and markers so developers can find their way, but actual documentation is best placed in separate files outside of the code.