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.

  • 1
    Why isn't your code documenting itself? Self-descriptive code is the 'truest' form of documentation. – JᴀʏMᴇᴇ Apr 11 '18 at 10:51
  • 2
    @JᴀʏMᴇᴇ sometimes it is hard to write code like this_method_does_that_but_because_business_decided_this_and_that_i_do_it_like_this(params). There are circumstances where it is smarter to elaborate in prose than in code. – Thomas Junk Apr 11 '18 at 15:11
  • 1
    @JᴀʏMᴇᴇ To put a finer point on Thomas Junk's comment: Self-documenting code documents what it does. It doesn't document why it does it that way. – Blrfl Apr 11 '18 at 15:12
  • 1
    @JᴀʏMᴇᴇ Even self-descriptive code should include comments of business logic. It might be easy to interpret that the code picks up a file and puts it somewhere else. But why does it go to folder a on this server and then on every other Tuesday if it's between 9:20-9:45am PST it goes to folder b. Those are things that code just can't inherently explain. – Christopher Apr 11 '18 at 15:16
  • @Christopher - but the OP's asked explicitly about design decisions, not business decisions. – JᴀʏMᴇᴇ Apr 11 '18 at 15:25


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
   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.


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.

  • +1 for your project wiki suggestion. I made an edit to my question (which was a spin in your bubble vs. quicksort style commenting decision) - and then saw that you already provided the bubble vs quicksort decision dilemma and also provided your take on the question in my edit. So things like "you decided to implement bubblesort instead of quicksort or some other algorithm, I would not document that in code" - you would document that in a project wiki under a heading like "miscellaneous code design decisions"? – user7088941 Apr 12 '18 at 11:46
  • @user7088941 As long as you do not exactly call it "miscellaneous code design decisions" yes XD – Thomas Junk Apr 12 '18 at 12:45
  • The problem with documenting outside the source code, or at least outside the repository, is that these other places change over time, and die altogether. If your design decisions are in the code repo, they last as long, and move with, the code, even as it moves, for example, from SVN to Git. – Jonathan Giddy Apr 16 '18 at 7:09
  • @JonathanGiddy Hm....this is a really.good.point! Since by now I've convinced myself that I have some big chunks of documentation lying around that will fit nowhere inside the source code as a comment, do you have an idea how to best integrate this documentation outside the source, but in a way to prevent loosing this when the code gets moved, as you described? – user7088941 Apr 17 '18 at 12:18
  • @JonathanGiddy that is dependend on the location where the code is hosted. If it is hosted as open source on github, bitbucket, younameit, it will at least last as long, as these services last. If it is hosted in a company it will last as long as the project lasts or is of worth. I see no actual objection in what you wrote. Perhaps you describe an actual scenario where code developed recently has these problems. – Thomas Junk Apr 17 '18 at 19:00

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.

  • 1
    +1 for the code location. But please see my edit for a tricky use case, for which your principle "put the documentation in the place where it is most likely to be found" doesn't apply. – user7088941 Apr 12 '18 at 11:36

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.

  • 1
    +1 for code diverging from comments. very true! This actually inspired me to ask a follow-up question. – user7088941 Apr 12 '18 at 11:21

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.

  • Not sure why this was down-voted. Works very well with the likes of swagger. And, in fact, as my comment on the OP implies - anything above and beyond this would lead me to ask other questions about the state of my code. – JᴀʏMᴇᴇ Apr 11 '18 at 10:53
  • @Martinc C +1 for the good idea regarding the readme. But I can't quite follow, the language I'm coding has specific syntax reserved for comments. Are you implicitly assuming my language supports XML style comments or that I'm using some kind of preprocessor that automatically removes in order to compile? – user7088941 Apr 12 '18 at 11:50

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.

Your Answer

