HN Explorer

Ask HN: Keeping track of the business rules

6 points by evaldas_a ↗ HN
I am looking for the best way to keep track of the business rules for both developers and everybody else (support staff / management) in a startup enviroment. The challenge is that our business model requires quite a lot of different business rules, which are created pretty much on the fly and evolving organically after that. After running this project for 3+ years, we have so many of such rules that often the only way to be sure about what the application is supposed to do in a certain situation is to go find the module responsible for that process and analyze its code and comments. That is all fine as long as you have one single developer who created the entire application from the scratch, but every new developer needs to go over pretty much entire codebase in order to understand how the application works. Even bigger problem is that non technical employees don't even have that option and therefore are forced to ask me pretty much every day how some certain case would be handled by the application.

Quick example - we only start charging for our customer campaigns once they have been active for at least 72 hours, but at the same time we stop creating invoices for campaigns that belong to insolvent accounts and close such accounts within a month of the first failed charge. That does not apply to accounts that are set to "non-chargeable" which most commonly belongs to us since we are using the service ourselves. The invoices are created on the 1st of each month and include charges from the previous month + any current balance that the account might have. However, some customers are charged only 4 days after their invoice has been generated due to issues with their billing department. In addition to that, invoices are also created when customer deactivates his campaign, but that can only be done once the campaign is not longer under mandatory 6 month contract, unless account manager approves early deactivation.

I know, that's quite a lot of rules that need to be taken into account when answering a question "when do we bill our customers", but actually I could still append an asterisk at the end of each sentence in order to disclose some rare exceptions. Of course, it would be easiest just to keep the business rules to the minimum, but we need to adapt to changing marketplace - i.e. less than a year ago we had no contracts whatsoever.

One idea that I had so far was a simplistic wiki with categories corresponding to areas such as "Account activation", "Invoicing", "Collection procedures" and so on. Another idea would be to have giant interactive flowchart showing the entire customer "life cycle" from prospecting to account deactivation.

What are your experiences / suggestions?

5 comments

[ 3.1 ms ] story [ 24.4 ms ] thread
briandoll
Attempting to keep track of business rules in a system other than your code base will cause more problems than it will solve, and it will _always_ be out of date.

Every business of a certain age has more business rules than any one person can keep in their head at one time. These rules manifest themselves in your code. They are the business rules. Everyone has their own opinion on what the rules are, but the developers know the answers are in the code, not in our foggy memory.

Now that we know what business rules are and where we keep them, we need to think about how we organize them. Instead of a business problem, we have a technical problem. Organizing 'business rules' becomes organizing software. This is a well-worn field, so you'll find lots of good advice on domain-driven design and the organization of software (object-oriented or otherwise).

A related software principal here is 'tell, don't ask' (http://pragprog.com/articles/tell-dont-ask). This is especially important in environments with lots of conditional rules, which must be considered at various times.

evaldas_a
Thanks a lot for your comment. Is "attempting to keep track of business rules in a system other than your code base will cause more problems than it will solve" true even if you track business rules only on high level? I.e. let's say that such auxiliary system does not track how often certain check is performed, but it does inform that such checks exist? In my case that means that we periodically check your website to see that the webpage targeted by the campaign is still up and containing certain information - do you feel like capturing such data outside the codebase is hopeless?
briandoll
What is likely very valuable is understanding at a high level, the intent of your rules. For example, you might say that you verify the relevance of your campaigns. How you verify that will change over time, but the business value is that you verify them somehow. Then, instead of thinking of them as documented business rules, you can see them as marketable values your service provides.

I've built several eCommerce back-ends, for example, and they each had a ton of very specific rules that were unique to the businesses, the products they sold, and the type of customers the services targeted. If you want to know precisely how the site validated address and credit card information, you'd really need to check the code. However, you could certainly say (and market) that you provide security measures to prevent fraud.

The snag to avoid is attempting to document the specifics of the rules anywhere but the code itself.

evaldas_a
One more question - so if we agree to keep the documentation within the code, are there any rules outside of using MVC / choosing good naming conventions that would help to undestand what's going on for somebody who is knew to the project?

I.e. right now the only way a new developer can find out that we create invoices upon campaign deactivation would be by doing search in project files for instances where invoicing module is called. Is it possible to have some auto documenting system which could list all files w/ line numbers where specific function is called?

briandoll
The best way for a new developer to get to know the domain model and to understand the business rules is to read through the test suite first. From there the new developer may read through the implementation of the domain objects, controllers, etc.

This assumes, of course, that the application is well designed, continually refactored and well tested. Every app has skeletons in the closet, though, and this perfect world often leaves something to be desired.

If your code is relatively clean though, you'll have one and only one place where you instruct an account to be invoiced, and you can trace through that code anytime you have questions about how that scenario works.

Suggestion: Every time you go diving into the code to investigate some scenario and wish to discover the business rules, start by writing a test for it. Write tests that expect that behavior, then execute the scenario and ensure your tests pass. Better yet, write those test first and you're all the way there. :)