How can I greatest doc a code design choice in my supply code? Ought to I simply add a large remark at some extent I really feel is correct?
Or ought to I simply create a separate file?
This difficulty is essential for me, as a result of the mission that I am workign on sooner or later could also be taken over by another person (or maybe I’ll return to it after leaving it for years) and he has to know why I took some code design choice ultimately and never in another manner.
Ideally I would wish to generate the documentation for my code out of the code feedback (e.g. with reStructuredText), so I would be eager to know what my choices are.
EDIT Here is a difficult use case: Suppose I’ve a way that produces one thing. The factor it produces may have been achieved by method A,B or C, that are all apparent. I selected method C, as a result of after selecting A and B it turned out that there are literally critical downsides to that (e.g. relying on a third social gathering library, that turned out to be not properly maintained, after the developer of that library was contacted and so forth.), however these draw back will not be instantly clear.
Explaining all that in a remark beneath that technique would make the code type of unreadable, as a result of an enormous block of remark would separate the strains of code. So what could be the most effective method to deal with this?
Transferring the feedback in a separate file will end in that file by no means being learn. Making a pointer to that file can also be not a good suggestion as a result of that will type of break the clear construction the mission: The whole lot is neatly commented in just a few strains within the supply code – after which there’s since bizarre file laying round, containing one huge remark.