Question

What have you found to be the best way to document (put comments on) a complex ORM query, specifically a LINQ to EF query or an nHibernate criteria query?

Answer 1

Unit tests or specifications against the service layer.

    [TestMethod]
    public void ItemsForBill_returns_expected_items_with_explicit_customer_id()
    {
        var customer = new Customer { Id = new Guid("{AB2F33FA-92E0-4B7C-8720-901CD9918796}") };
        var expectedItemId = new Guid("{B1493898-A832-4D83-A134-77790673A6D6}");
        var start = new DateTime(2010, 1, 1);
        var stop = new DateTime(2010, 1, 31);
        var items = new[] 
        {
            new Item 
            {
                Description = "Date out of range",
                ItemDate = new DateTime(2010, 2, 10),
                Payer = customer,
                PayerCustomerId = customer.Id
            },
            new Item 
            {
                Description = "Should be included",
                Id = expectedItemId,
                ItemDate = new DateTime(2010, 1, 10),
                Payer = customer,
                PayerCustomerId = customer.Id
            },
            new Item 
            {
                Description = "Wrong payer",
                ItemDate = new DateTime(2010, 1, 10),
                Payer = new Customer()
            }
        };
        var uow = new FakeBillingUnitOfWork();
        uow.SetTestData(items.ToList());
        var activity = new SelectItemsForBillingRun();
        var input = new BillingRun
        {
            OneCustomerId = customer.Id,
            Start = start,
            Stop = stop
        };

        var result = activity.ItemsForBillingRun(uow, input);

        Assert.IsNotNull(result);
        Assert.AreEqual(1, result.Count());
        var returned = result.Single();
        Assert.AreEqual(expectedItemId, returned.Id);
    }