> It seems like that would be even more likely to drift than inline comments. I'm not sure why that matters to utility. If you don't check the documentation/c

> It seems like that would be even more likely to drift than inline comments. I'm not sure why that matters to utility. If you don't check the documentation/comments and code in a changeset, you are going to get drift. This is regardless of the documentation methodology. How poorly developers maintain code is a constant in the case of drift (lack of rigor), so the method is irrelevant, except in how descriptive it can be. A complex application is a nested logical structure tied to orthogonal business requirements. This is why READMEs and docs folders exist, alongside large block comments, hidden amongst the code. How to best describe code is definitely not to inline it, as that's too limiting for what is to be described.