Documenting design decisions in code comments?

Question

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.

Thank you.

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.

Answer 1

How can I best document a code design decision in my source code?

The answer depends on your understanding of »best« and »design decision«.

What design decision I document in code:

As with all comments, I like having not more comments than necessary to undestand what is going on in the code. When reading code, I expect that the code is written in a way that makes it obvious what is going on. Accordingly I document my code.

Contrieved example ahead:

def calculate_total_of_articles(articles):
...
   return total

In this context, it should be clear, what this code does; it calculates the total of a collection of articles. No further comment necessary.

Say there is a new business requirement, that makes deviating from what one might expect necessary - say: if article abcd is in the list, one is for free - I would document this deviation in code:

def calculate_total_of_articles(articles):
"""calculates the total, but according to business decision
   https://ourtrackerwahtever.com/issue1234
   one of abcd comes for free
   ...
"""

I explain

• what is different
• why it is different
• where to find the details / reason for that decision

Another example: Say, you have to sort articles by name. And you decided to implement bubblesort instead of quicksort or some other algorithm, I would not document that in code. I expect, that code is written in the way it is for a reason. If I have doubts about the decision made or have a proposal for improvement, I ask the original author and come up with my proposal how to improve. I do not expect a comment like

I know bubblesort is ugly but in this very case it is the best solution

Usually the context should be clear why you did that.

Should I just add a massive comment at a point I feel is right? I see no advantage in that.

For me a source file is about instructions, which tell me what should be done or what is expected this code should be doing. The question of why is secondary for me: even if it is

voices in my head told me to write the code in this way

As I said above: of course exceptional expectations should be documented - but in a way, which doesn't impede reading flow. Reasons could be given elsewhere. And if the reader is interested, he might follow, but she/he should have to leave the context of reading code.

Or should I just create a separate file?

I struggle with that. What file could that be? You could do it in a documentation section. But on the other hand, as a developer I expect from a documentation, that it tells me how to achieve possible goals, how to use the code, but not a secret diary of why you did certain things.

The longer I think about, the more I come to the conclusion:

No. A separate file isn't a good place - as long as it comes alongside your code.

---

tl;dr

So where to document reasons/decisions?

• Project Wiki

• Project (Bug-)tracker

• Project Page

• Project Blog

These are the best, if you accept the premise of keeping your codebase free of things not related to understand the code and avoiding lengthy explanations.

Answer 2

I would argue it depends on the scope of your description.

If your design decision is so granular that it's fully implemented in a single method, then a comment next to that method would be appropriate.

If your design decision affects a single class, you'd want to document it with the class.

If your design affects the entire project, then you should probably put the documentation into it's own file.

In short, put the documentation in the place where it is most likely to be found.

Answer 3

If the explanation needs to be very long, put a brief summary as a comment in the code with a pointer to the more detailed one in out-of-line docs.

In general it's very good practice to make the code document itself as much as possible, trying to keep the comments to a minimum (but not less!), because this way it is easier to follow and with time code has a tendency to diverge from comments.

There are of course cases where this is not easy or possible, and in those cases you have to resort to comments to make the code clear enough.

Answer 4

Document your code with XML documentation comments. You gain ability to automatically extract documentation files from these source files at runtime.

XML comments can be used to describe what method/class do.

Some high-level architecture assumptions you can place in README files.

Answer 5

Definitely document in the source code, for the next reader, even if you are the most likely to be the next reader. When you encounter a bit of tricky logic after a few years, you'll thank yourself.