This is the fifth article in an ongoing series on Clarion embed points and how almost all Clarion developers use them in the wrong way. If you haven't read the first article in the series, then you might find that statement offensive. You might be thinking, "What does Harms know anyway? I'm a professional developer. I know how to write embed code."
...
Once again, here's the idea in a nutshell:
Embed code
...
should not
...
contain business logic.
Put another way, your app contains code that gives it unique value to your users/customers. Don't bury that code inside embed points. You can call it from embed points (you'll almost certainly have to) but don't let it live there. Good code needs a home, a place where it can be conceived, nurtured, and yes, tested and disciplined.
...
I think it almost always looks like a class library, and I've taken some heat for saying that. In this article I'll defend my point of view, and I'll do it by beginning a transformation of the Invoice application which ships with Clarion.
The Invoice app
The example Invoice app isn't something you'd want to use in real life, but I've chosen it because we all have it, and because many of us have, at one time or another, had to deal with invoicing.
Figure 1 shows the customer order window, which has a child browse showing line items for each invoice.
Figure 1. Browsing orders for a customer
Figure 2 shows the order detail form. Yeah, I know, none of this is pretty. But that's okay - it's old example code, and Clarion devs sometimes have to deal with old code.
Figure 2. Changing a detail record
Here's the Detail file structure:
...
In Figure 3 I've added the calculated fields as display strings. I've also added a button to force a call to the CalcValues routine so I can see the results of several changes at one time.
Figure 3. Displaying the calculated fields
In Figure 3 I've added a new detail line, and I've selected an Aster, quantity two2. I've pressed the Recalculate Values button. You , and you can see that the values all appear to be correct.
In Figure 4 I've changed the tax rate to 5%.
Figure 4. Setting the tax rate
So far, so good.
In Figure 5 I've added a 10% discount.
Figure 5. Adding a discount
Whoops. The discount is calculated as $3.00, which is correct, at least for the total if not for the per-item price (the Invoice app has no formal notion of "extended" price). Why then is the savings only $1.65?
In Figure 6, I've set tax rate to 5% and the discount to 1%.
Figure 6. A 1% discount and a negative savings
According to Figure 6, offering a 1% discount to a customer results in a negative savings. Interesting.
In Figure 7, the wheels have well and truly come off.
Figure 7. Setting the tax rate to zero
I've set the discount rate and the tax rate to zero, but I'm still showing a tax paid of $1.50, a discount of 30 cents, and a savings of $-1.19.
...
The solution is to take the code out of the embed and put it somewhere it can be both reused and tested.
The beautiful black box
The important thing about business logic is that you should be able to use it without having to know exactly how it works. That may sound a bit counterintutive counter intuitive - after all, if it's your own code, shouldn't you know how it works? If you wrote it, yes, you should. But we all use black box code all the time. How many Clarion devs really know what's going on in Windows when a mouse is moved or a button clicked? How about the file driver system? Or even ABC? We don't need to know how these things all work; we just need to know how to use them.
...
- Total price
- Tax amount
- Discount amount
- Total cost
- Savings
How to design a black box
Once you know the inputs and outputs, it's easy to design your black box. You just need to decide whether to create your black box as a procedure or a class.
Here's how you might declare a black box procedure to replace the CalcValues routine:
...
And here's how you could declare a similar black box class to replace the CalcValues routine:
InvoiceDetail Class Init Procedureprocedure(*decimal price,| long quantity,| *decimal discountRate, | *decimal taxRate) GetTotalCost procedure(*decimal totalCost) GetTaxAmount procedure(*decimal taxAmount) GetDiscountAmount procedure(*decimal discountAmount) GetSavings procedure(*decimal savings) End
...
There isn't all that much difference between the two approaches so far. The procedural syntax takes a little less typing, but it's also slightly more difficult to understand. It's easier to make a mistake with eight parameters than it is with four, and . In the case of the class if you wanted to be very sure the class it was used correctly you could always create individual setter methods for each of the four initialization parameters (and report an error if not all were set before a value was requested).
...
As well, the procedural code can really only be used as procedural code. That is, you're using the class pretty much as a set of procedures, but you can also use the class instance itself. You could, if you wish, create an InvoiceHeader object that contains a list of InvoiceDetail objects, such that you could model the entire invoice in memory. It's very difficult to do anything like that with procedural code. I'll get more into the advanced uses of the InvoiceDetail class in future articles.
It's also easier to extend the InvoiceDetail class without breaking existing functionality. As written, the CalcValues routine calculates total cost , including taxes , but not extended price excluding taxes. Adding a method to get the extended price would have zero effect on code already using the class, whereas with the procedural solution you'd have to make the additonal additional parameter ommitableomittable.
In this very limited set of calculations and results, the procedural approach is already starting to show some strain. What happens when things get really interesting, as when you need to start tracking multiple taxes instead of a single tax?
In other words, the evolution of programming from procedural code to object-oriented code isn't without very good reason. OOP really does give you a greatly expanded toolbox for solving programming problems.
Testing
Whichever approach you take, procedural or class, your code needs to be testable. And I don't mean the kind of testing that involves someone running an app, entering values, and making sure the results are correct. Yes, you do still need to do that, but by the time your code gets to that point you should already have a high level of confidence in the underlying logic.
The kind of testing I'm talking about is called "unit testing". The "unit" refers to the smallest testable parts of the application. In the case of the procedural version of the above code, it would involve testing a single call to the CalculateInvoiceDetailValues procedure. In the case of the class version, you would have a test for each of the methods which return a value.
That brings up another advantage of classes - it's easier to break testing down into smaller units.
The idea behind unit testing is that if all of the individual objects (or procedures) that make up your application work properly , you're much more likely to have an application that works properly as a whole.
As well, unit testing is a great way to prevent detect the introduction of new bugs as you make modifications to existing code. If you have a large suite of unit tests, and you make a change to some core code that affects how other methods or classes (or procedures) work, any bugs introduced by those changes stand a good chance of showing up in the unit tests.
...
Another key is to avoid outside dependencies in unit tests, such as a requirement to use an actual database or a user interface widget. You want your unit tests to run as quickly as possible, and with little to no chance of breakage due to something on the outside of the tested code not being set up correctly. Tests that take too long to run or are dependent on proper configuration are tests that tend not to get run.
In the case of the CalcValues routine code, isolation is pretty easy to achieve. Although the routine code operates directly on the fields in the Detail record, this isn't a requirement. The logic can all be made internal to the class; that way the class can be used anywhere at all without modification, and the only embed code needed is whatever it takes to assign the values to and from the class. Presto! You've successfully removed the business logic from the embed point!
What's next
There are a couple of ways to approach unit testing. One is to take existing code, refactor it if necessary to make it testable, and then write a bunch of tests to see whether it's working as you expect. The other is to start by writing tests, and then create the code to make those tests compile and then pass. This latter approach is called test-driven development (TDD) and can be enormously useful. Although I do have some existing code to work with, it's broken enough that I'm going to start fresh, using the routine code only as a reference.
...
The downloadable source zip contains the modified Invoice app shown above, in C7 format.