Yesterday, I called this code unprofessional, and it is.

The reason that I call this code unprofessional is that it is a black box. Oh, sure, this is a great code in terms of readability and understand what is going on. But it is also a very complex piece of code, with a lot of things that are going on and it is in a critical location.

This sort of code cannot be a black box. Case in point, take a look at this email thread. We have a customer who is trying to understand why dynamic indexes are being created, when he has the proper indexes to answer query.

And I had to ask a lot of questions to figure out what the problem was. Turned out, it is by design issue, but we could fix that .

That is not a good place to be. I want my customers to be able to figure those things on their own.

That is why the code now looks like this:

And you can ask RavenDB to explain how he got to a specific decision.

For example, when we want to figure out why a specific index was selected (or, more likely, was not selected), we can issue the following request:

http://localhost:8080/databases/HibernatingRhinos.Orders/indexes/dynamic/Orders?query=OrderNumber:1293182&explain=true

Which will give us the following output:

[
   {
      "Index":"Auto/Orders/ByContractIdAndPayments_PaymentIdentifier",
      "Reason":"Can't choose an index with a different number of from clauses / SelectMany, will affect queries like Count()."
   },
   {
      "Index":"Freebies/Search",
      "Reason":"Index does not apply to entity name: Orders"
   },
   {
      "Index":"Orders/Search",
      "Reason":"The following fields are missing: "
   },
   {
      "Index":"Orders/Stats",
      "Reason":"Can't choose a map/reduce index for dynamic queries."
   },
   {
      "Index":"Products/Stats",
      "Reason":"Can't choose a map/reduce index for dynamic queries."
   },
   {
      "Index":"Raven/DocumentsByEntityName",
      "Reason":"Query is specific for entity name, but the index searches across all of them, may result in a different type being returned."
   },
   {
      "Index":"Test",
      "Reason":"Index does not apply to entity name: Orders"
   },
   {
      "Index":"Trials/Search",
      "Reason":"Index does not apply to entity name: Orders"
   },
   {
      "Index":"Auto/Orders/ByOrderNumber",
      "Reason":"Selected as best match"
   }
]

As you can see, that is a pretty good way to debug things, in production, without any complex steps or dedicated tools.

And, like in the previous example, reducing support costs is important.