Single-Point-of-Definition by Example
Steven Feuerstein lists seven excellent “Golden Rules” in his presentation (via Eddie Awad) and says “Don’t repeat anything. Aim for a Single Point of Definition for every aspect of your application – formulas, business rules, magic values, SQL statements.” giving the following code as exhibit A:
I’m guessing in his presentation he spoke about various things that could be done to improve this code, but they’re not in the PDF; so I’d like to give it a go myself and see how much we can improve the maintainability of this code by reducing hard-coding.
1. Type Declarations
Instead of declaring parameters and variables as NUMBER, VARCHAR2 etc, these should use the %TYPE operator so that they are automatically synchronized with the datatype from the table columns they represent:
PROCEDURE process_employee (department_id_in IN employees.department_id%TYPE) IS l_id employees.employee_id%TYPE; l_salary employees.salary%TYPE; ...
l_name, however, is not based on any table column we know of at this point; so there is no %TYPE we can use for it. But bear with me, we’ll fix this later.
2. Magic Values
This one’s a no-brainer: that “10000000” is obviously a magic value that some bean-counter decided was the correct threshold for the CEO’s salary. Whatever.
You might define this as a constant defined in a global package specification, e.g.
CREATE PACKAGE employee_constant AS ceo_salary_threshold CONSTANT employees.salary%TYPE := 10000000; END employee_constant;
Personally, I’d suspect that the business will review and revise this number from time to time, to keep up with inflation; so we might end up needing a database table to store the current threshold, plus a date range for which the threshold applies. I’d then add an interface on top of this table so that queries and procedures don’t need to know how to get the current threshold. We can retrofit this later by changing ceo_salary_threshold into a function instead of a constant. That’s a bit beyond the scope of this exercise, however.
3. Formatting Rules
The rule about formatting an employee name as “LAST,FIRST” is duplicated in a comment and in the SELECT statement; and chances are it will be required elsewhere in the application as well. My preferred method for creating a SPOD for this sort of business rule used to be to move the implementation into a view, e.g.:
CREATE VIEW formatted_employees AS SELECT employees.*, employees.last_name || ',' || employees.first_name AS full_name FROM employees; COMMENT ON COLUMN formatted_employees.full_name IS 'Full name: LAST COMMA FIRST (ReqDoc 123.A.47)';
This view is what I like to call a “formatting” view: it is only allowed to query one table, it contains no WHERE, GROUP BY or HAVING clauses, and it selects all the columns from the table. The view can be used almost anywhere the table may be used. It adds additional columns that format the data in various ways. If need be, we can even add INSTEAD OF triggers to handle inserts/updates on the derived columns – if the business rules make the conversion from derived-to-underlying-column well defined.
So, now we can redefine the cursor as:
CURSOR emps_in_dept_cur IS SELECT employee_id, salary, full_name AS lname FROM formatted_employees WHERE department_id = department_id_in;
Notice that I don’t call the column “last_comma_first” or anything like that – that would again be hard-coding the business rule, which would then be replicated throughout the application. In Oracle 11g, however, I think it might be better to create virtual columns on the table instead:
ALTER TABLE employees ADD ( full_name VARCHAR2(100) GENERATED ALWAYS AS (last_name || ',' || first_name) VIRTUAL ); COMMENT ON COLUMN employees.full_name IS 'Full name: LAST COMMA FIRST (ReqDoc 123.A.47)'; CURSOR emps_in_dept_cur IS SELECT employee_id, salary, full_name AS lname FROM employees WHERE department_id = department_id_in;
The virtual column can have its own stats, and even an index if needed for querying.
Another option would be to create a function that does this formatting:
CREATE FUNCTION employee_full_name (last_name IN employees.last_name%TYPE, first_name IN employees.first_name%TYPE) RETURN VARCHAR2 DETERMINISTIC IS --Full name: LAST COMMA FIRST (ReqDoc 123.A.47) BEGIN RETURN last_name || ',' || first_name; END employee_full_name;
We could call this function from the procedure or the view, but if we’re on 11g there’s no reason we can’t create a virtual column on it:
ALTER TABLE employees ADD ( full_name VARCHAR2(100) GENERATED ALWAYS AS (employee_full_name(last_name,first_name)) VIRTUAL );
Another advantage to using the view or a virtual column is that we can now remove the “VARCHAR2 (100)” from the variable declaration, e.g.:
4. Cursor Parameter
The cursor refers directly to the parameter to the procedure, which is a no-no – this couples the cursor too much with the procedure, i.e. we can’t re-use it elsewhere unless we always define a variable “department_id_in”. Instead, we should use a cursor parameter:
CURSOR emps_in_dept_cur (department_id_in IN employees.department_id%TYPE) IS SELECT employee_id, salary, full_name AS lname FROM employees WHERE department_id = emps_in_dept_cur.department_id_in;
The addition of the context “emps_in_dept_cur.” is not strictly necessary, but it is good practice to define the scope of all variables so that unrelated changes (e.g. the addition of a column called “department_id_in”) don’t change the code.
5. Cursor Row Type
What if we need to add 10 more columns to the cursor? At the moment we’re adding one more variable for each column of the cursor, and specifying it three times (variable declaration, cursor SELECT clause, and the FETCH INTO). We can reduce this to just once by declaring a cursor row type instead:
PROCEDURE process_employee (department_id_in IN employees.department_id%TYPE) IS CURSOR emps_in_dept_cur (department_id_in IN employees.department_id%TYPE) IS SELECT employee_id, salary, full_name lname FROM employees WHERE department_id = emps_in_dept_cur.department_id_in; TYPE emps_in_dept_cur_type IS emps_in_dept_cur%ROWTYPE; emp emps_in_dept_cur_type; BEGIN OPEN emps_in_dept_cur; LOOP FETCH emps_in_dept_cur INTO emp; ...
6. Don’t COMMIT
Procedures should rarely COMMIT (there are very few exceptions to this rule, e.g. procedures declared as autonomous transactions). Transactional control should be left to the calling process – this process might need to be done along with a number of other changes elsewhere, and we would want to either COMMIT or ROLLBACK all the changes together as one transaction. What if the next procedure raised an error and we had to rollback? Our system would be left in an inconsistent state.
7. Error Package
That RAISE_APPLICATION_ERROR hard-codes an error code and an error message. What if we type the error number wrong somewhere? If the calling process handles ORA-20907 in some fashion, but we mistype it as -20908 in one procedure, the calling process will not handle it.
We could declare an exception instead, e.g. in a global package specification:
CREATE PACKAGE employee_exception AS invalid_dept_id EXCEPTION; PRAGMA EXCEPTION_INIT (invalid_dept_id, -20907); END employee_exception;
Now, our exception handler can raise just the one exception:
EXCEPTION WHEN NO_DATA_FOUND THEN RAISE employee_exception.invalid_dept_id;
However, we’ve now lost the error message. It would be better to create an error-handling package instead:
CREATE PACKAGE employee_error AS invalid_error_no CONSTANT NUMBER := -20000; invalid_error_no_exception EXCEPTION; PRAGMA EXCEPTION_INIT (invalid_error_no_exception, -20000); invalid_dept_id CONSTANT NUMBER := -20907; invalid_dept_id_exception EXCEPTION; PRAGMA EXCEPTION_INIT (invalid_dept_id_exception, -20907); PROCEDURE raise_exception (error_no IN NUMBER); END employee_exception; CREATE PACKAGE BODY employee_error AS PROCEDURE raise_exception (error_no IN NUMBER) IS BEGIN CASE error_no WHEN invalid_dept_id THEN RAISE_APPLICATION_ERROR(invalid_dept_id, 'Invalid department ID'); ELSE RAISE_APPLICATION_ERROR(invalid_error_no, 'Bug: invalid error number'); END; END message; END employee_exception;
EDIT: PRAGMA EXCEPTION_INIT only accepts literal numbers for its second parameter (or else you get PLS-00702 at compile time) – fixed accordingly
Now, our exception handler is nicely modular:
EXCEPTION WHEN NO_DATA_FOUND THEN employee_error.raise_exception(employee_error.invalid_dept_id);
So now, our code looks like this:
PROCEDURE process_employee (department_id_in IN employees.department_id%TYPE) IS CURSOR emps_in_dept_cur (department_id_in IN employees.department_id%TYPE) IS SELECT employee_id, salary, full_name lname FROM employees WHERE department_id = emps_in_dept_cur.department_id_in; TYPE emps_in_dept_cur_type IS emps_in_dept_cur%ROWTYPE; emp emps_in_dept_cur_type; BEGIN OPEN emps_in_dept_cur; LOOP FETCH emps_in_dept_cur INTO emp; IF emp.salary > employee_constant.ceo_salary_threshold THEN adjust_comp_for_ceo (emp.salary); ELSE analyze_compensation (emp.employee_id, emp.salary, employee_constant.ceo_salary_threshold); END IF; EXIT WHEN emps_in_dept_cur%NOTFOUND; END LOOP; EXCEPTION WHEN NO_DATA_FOUND THEN employee_error.raise_exception(employee_error.invalid_dept_id); END;
One final change that one might make here is to move the SQL query right out of the procedure and use a ref cursor instead, supplied by a central “employee_cursor” package.
There are probably plenty of other changes we could make to improve the maintainability of this code further.
What do you think?
11 June 2010 - 1:58 pm
I’d expand the COMMIT reasoning to directly relate it to ‘hard-coding’. By including a COMMIT you are saying ‘this procedure is the end of the transaction’. By leaving the COMMIT to the calling routine, you have the flexibility of calling the routine at any point in a transaction.
4 October 2010 - 4:51 pm
I didn’t test my code all that well. The exception_init stuff would have raised “PLS-00702: second argument to PRAGMA EXCEPTION_INIT must be a numeric literal” – I’ll update the article accordingly.