I'm glad to know I'm not the only person who works this way. My source files often have a paragraph or two at the top that explains my intentions for that class/module as well as explains the usage of my domain language. I never see this in other people's code though.
I agree with people who say that the code itself should read very clearly, but the fact is that even when writing an article or paper you have to disambiguate your own writing, clarify your usage of terms and present some context up front. Otherwise people can take away a very mistaken impression of your text, and it is certainly no less true for code.
I agree with people who say that the code itself should read very clearly, but the fact is that even when writing an article or paper you have to disambiguate your own writing, clarify your usage of terms and present some context up front. Otherwise people can take away a very mistaken impression of your text, and it is certainly no less true for code.