How can I best document a code design decision in my source code? Should I just add a massive comment at a point I feel is right?
Or should I just create a separate file?
This issue is important for me, because the project that I'm workign on in the future may be taken over by someone else (or perhaps I will return to it after leaving it for years) and he has to understand why I took some code design decision in some way and not in some other way.
Ideally I'd want to generate the documentation for my code out of the code comments (e.g. with reStructuredText), so I'd be keen to know what my options are.
EDIT Here's a tricky use case: Suppose I have a method that produces something. The thing it produces could have been achieved by approach A,B or C, which are all obvious. I chose approach C, because after choosing A and B it turned out that there are actually serious downsides to that (e.g. depending on a 3rd party library, that turned out to be not well maintained, after the developer of that library was contacted etc.), but those downside are not immediately clear.
Explaining all that in a comment below that method would make the code kind of unreadable, because a big block of comment would separate the lines of code. So what would be the best approach to handle this?
Moving the comments in a separate file will result in that file never being read. Creating a pointer to that file is also not a good idea because that would kind of break the clean structure the project: Everything is neatly commented in a few lines in the source code - and then there's since weird file laying around, containing one big comment.