Programming Style Guide: Command Query Separation

An important aspect of programming, and one that people don’t think of to often, is being able to express the intentions of the code clearly.

Most of the times we programmers get lost in the code we write. It is important to step back and take a look at the code we have written from another person’s perspective. One can say, “But that’s what documentation is supposed to do right? Provide information to others!”. Yes, but that’s not the only way. A good example of that is a situation we often face with functions.

Command Query Separation

Most functions can be generalised into 2 categories.

Command Functions

Functions that act on instructions sent to it and make changes to the underlying data/model. These are commands given to a function and the callee is not expecting a response.

Query Functions

Functions that are used as queries to examine the underlying data/model. The callee is most certainly expecting a response. The function should not modify the underlying model in any way.

It is not common to find a function that does both. In fact, to be consistent command functions must never return a response and a query function must only return a response. This is how ideal separation happens. This way programmers can easily distinguish between Commands & Queries and the objective of the function becomes clear.

The real world however is quite different. Most functions we write are not guaranteed to work the way we want. The likelyhood of an error occurring while a function is being run is very high. This can happen during data validation or some underlying process. Hence, most functions are very likely to return a response indicating the success of a function. This is done using a variety of techniques. It is this feature that throws Command Query Separation for a toss.

In this article we are going to look at some ways in which we can achieve Command Query Separation while still retaining error handling capabilities.

Let us start by looking at the example written below.

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: Value of type double. The result of the division is returned. If the denominator is 0 the function returns 0
*/
double division(const double &firstNumber, const double &secondNumber)
{
     if (!floating_point_equality(firstNumber, secondNumber))
     {
          return firstNumber / secondNumber;
     }
     return 0.0;
}

The function is a rather simple implementation of division written in C++. It is meant to be a Query function. It immediately becomes clear that we are trying to do 2 things here:

  • We are trying to perform a division
  • We are trying to check if the division succeeded with the help of a return value

The problem is the fact that the function returns error codes and the result the same way. Any programmer using this function will have to write the code to distinguish between the two.

In this case the error is represented by the value ‘0’. There is no way for the caller to tell if the result of the division was 0 or if there was an error. It gets even worse if the function is a pure command function. A pure command function ideally should not return anything. However we will have to return a value to account for errors.

Here is an example of a Command Function:

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: An error code in the form of an integer. A '0' indicates success. '-1' indicates division by Zero error.
*/
int display_division_of_numbers(const double &firstNumber, const double &secondNumber)
{
     if (!floating_point_equality(secondNumber, ZERO))
     {
          std::cout&lt;&lt;firstNumber&lt;&lt;&quot; divided by &quot;&lt;&lt;secondNumber&lt;&lt;&quot; = &quot;&lt;&lt;(firstNumber / secondNumber)&lt;<span id="mce_SELREST_start" style="overflow:hidden;line-height:0;"></span>&lt;std::endl;
          return 0;
     }
     else
     {
          return -1;
     }
}

As we can see the function is a command function. It shouldn't be returning a value. But we are forced to return a value to communicate success.

Let us look at some alternatives.

Returning Error Codes

This approach is the one that was implemented above & has the obvious short comings.

Passing An Error Code variable

This is the next best approach. Instead of returning an error code pass in an object that represents error. After the call is completed, check to see if the error object is nil/NULL. This ensures that the return value always corresponds to an answer and nothing else.

//Potential Error Codes

typedef enum ErrorCodes
{
DIVIDE_BY_ZERO, NaN, NEGATIVE_NUMBER
} ErrorCodes;

//ErrorCode struct. This is the object that contains error information
typedef struct ErrorCode
{
public:
     ErrorCode(const ErrorCodes &code, const std::string &description)
     :errCode(code), errDescription(description)
     {

     }

     std::string description() const
     {
          return errDescription;
     }

private:
     //Holds the code
     ErrorCodes errCode;

     //holds additional information
     std::string errDescription;
} ErrorCode;

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Argument 3: Holds a pointer to the error code object. If the object is nil then there was no error.
Returns: Value of type double. The result of the division is returned.
*/

double division_of_numbers(const double &firstNumber, const double &secondNumber, ErrorCode **error)
{
     if (!floating_point_equality(secondNumber, ZERO))
     {
          return firstNumber / secondNumber;
     }
     else
     {
          *error = new ErrorCode(DIVIDE_BY_ZERO, "Attempting to divide by zero");
     }
     return 0.0;
}

As is obvious from the code above, the return value always corresponds to the answer of the computation. All we have to do is check the ErrorCode pointer to see if it is NULL.

Here is the implementation for the Command Function.

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Argument 3: Holds a pointer to the error code object. If the object is nil then there was no error.
*/
void display_division_of_numbers(const double &firstNumber, const double &secondNumber, ErrorCode **err = NULL)
{
if (!floating_point_equality(secondNumber, ZERO))
{
std::cout<<firstNumber<<" divided by "<<secondNumber<<" = "<<(firstNumber / secondNumber)<<std::endl;
}
else
{
*err = new ErrorCode(DIVIDE_BY_ZERO, "Attempting to divide by Zero.");
}
}

As you can see the function looks like a true Command Function. There is no value being returned. However, the caller still has to check if the Error object is NULL.

Another implementation of this is to use a complex response.

//Potential Error Codes
typedef enum ErrorCodes
{
     DIVIDE_BY_ZERO, NaN, NEGATIVE_NUMBER, NO_ERROR
} ErrorCodes;

//Response struct. It will hold either the error or a response.
typedef struct Response
{
public:
     Response(ErrorCodes err)
     : errCode(err), value(0.0)
     {

     }

     Response(double answer)
     : errCode(NO_ERROR), value(answer)
     {

     }

     ErrorCodes getError() const
     {
          return errCode;
     }

     double getValue() const
     {
          if (NO_ERROR == errCode)
          {
               return value;
          }
          return 0.0;
     }

private:
     ErrorCodes errCode;
     double value;
} Response;

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: A struct of type Response that either contains the value or the error. The caller must examine the struct before probing the value.
*/
Response* division_of_numbers(const double &firstNumber, const double &secondNumber)
{
     if (!floating_point_equality(secondNumber, ZERO))
     {
          Response *answer = new Response(firstNumber/secondNumber);
          return answer;
     }
     else
     {
          Response *error = new Response(DIVIDE_BY_ZERO);
          return error;
     }
}

This approach is a combination of the first 2 approaches. It immediately sends information to the caller that he/she must examine the object for errors before probing for the value. In the earlier example, there is no guarantee that the caller will examine the error. There is no guarantee with this approach either. But at least it simplifies the implementation for the caller and provides an easier mechanism to handle errors without having to manually create error objects.

Something similar is achieved in Swift using Associated Enums.


//Response Enum. It will hold either the error or a response.

enum Response
{
     case Error(String)
     case Value(Double)
}

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: An Enum Response that either contains the value or the error. The caller must examine the struct before probing the value.
*/

func division_of_numbers(firstNumber : Double, by secondNumber : Double) -> Response
{
     if (!floating_point_equality(firstNumber : secondNumber, Equals: ZERO))
     {
          let answer : Response = Response.Value(firstNumber/secondNumber)
          return answer;
     }
     else
     {
          let error : Response = Response.Error("Dividing by Zero")
          return error;
     }
}

Of course the Swift implementation does not need a struct as enums allow us to encapsulate a value in them.

Exceptions & Exception Handling

This is a much better approach. The idea is that you write you function to work as it is normally supposed to. If something goes wrong throw an exception. This approach completely eliminates the need to examine the return value or check to see if there are errors in the response object.

In exception based programming, your code will follow the correct path if there is no problem. If an issue occurs then your code jumps to the part where the error needs to be handled.

Here is an example:

#ifndef MathException_hpp
#define MathException_hpp

#include
#include
#include 

namespace MathematicalExceptions {
     class MathException : public std::exception
     {
          public:
               virtual const char * what() const throw ();
               MathException(const std::string &information);

          private:
               std::string description;
     };
}
#endif /* MathException_hpp */

The next file:

#include "MathException.hpp"

const char * MathematicalExceptions::MathException::what() const throw ()
{
     return description.c_str();
}

MathematicalExceptions::MathException::MathException(const std::string &information)
: description(information)
{

}

the next file.

#include <span id="mce_SELREST_start" style="overflow:hidden;line-height:0;"></span>
#include
#include "MathException.hpp"

const double ZERO = 0.0;

//Floating point equality checker
/*
Argument 1: Holds the LHS value of type double
Argument 2: Holds the RHS value of type double
Returns: Boolean value
*/
bool floating_point_equality(const double &amp;firstNumber, const double &amp;secondNumber)
{
     return fabs(firstNumber - secondNumber) &lt; std::numeric_limits::epsilon();
}

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: A struct of type Response that contains the value.
This function throws an exception of type MathematicalExceptions::MathException
*/
double division_of_numbers(const double &amp;firstNumber, const double &amp;secondNumber)
{
     if (!floating_point_equality(secondNumber, ZERO))
     {
          double answer = firstNumber / secondNumber;
          return answer;
     }
     else
     {
          MathematicalExpections::MathException exception = MathematicalExceptions::MathException(&quot;Attempting to divide by zero&quot;);
          throw exception;
     }
}

int main(int argc, const char * argv[]) {
     double numerator = 32.1;
     double denominator = 0.0;
     double answer = 0.0;

     try
     {
          answer = division_of_numbers(numerator, denominator);
     }
     catch (MathematicalExceptions::MathException &amp;err)
     {
          std::cout&lt;&lt;err.what()&lt;&lt;std::endl;
     }
     return 0;
}

Exceptions are about the closest we can come to achieving Command Query Separation. Anyone using functions that implement the Exception throwing and handling capability is clear as to whether it is a Command function or a query function without compromising on safety and error handling in any way.

Here is an example with Swift.

//Exception Enum. Will be used to throw an exception for mathematical operations
enum MathExceptions : Error
{
     case Divide_by_Zero(String)
     case NaN(String)
     case NegativeNumber(String)
}

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
Returns: The value of type Double. The caller must handle any exceptions that might be thrown.
*/
func division_of_numbers(firstNumber : Double, by secondNumber : Double) throws -> Double
{
     if (!floating_point_equality(firstNumber : secondNumber, Equals: ZERO))
     {
          let answer : Double = firstNumber / secondNumber
          return answer;
     }
     else
     {
          throw MathExceptions.Divide_by_Zero("Attempting to Divide by zero.")
     }
}

let ans : Double = 0.0

do
{
     ans = try division_of_numbers(firstNumber: 22.3, by: 0.0)
}
catch let err
{
     print(err.localizedDescription)
}

Again, the Swift implementation is rather Straightforward thanks to Associated Enums which conform to the Error protocol.

Here is how the Command function would look with exceptions.

//Division function
/*
Argument 1: Holds the numerator of type double
Argument 2: Holds the denominator of type double
*/
void display_division_of_numbers(const double &amp;firstNumber, const double &amp;secondNumber)
{
     if (!floating_point_equality(secondNumber, ZERO))
     {
          std::cout&lt;&lt;firstNumber&lt;&lt;&quot; divided by &quot;&lt;&lt;secondNumber&lt;&lt;&quot; = &quot;&lt;&lt;(firstNumber / secondNumber)&lt;<span id="mce_SELREST_start" style="overflow:hidden;line-height:0;">&#65279;</span>&lt;std::endl;
     }
     else
     {
          MathematicalExceptions::MathException exception = MathematicalExpections::MathException(&quot;Attempting to divide by zero&quot;);
          throw exception;
     }
}

This produces a much better implementation of the function, while maintaining the error handling capabilities.

Conclusion

As we can see implementing perfect Command Query Separation is not easy. But by writing our functions properly and by using better error handling such as exceptions it becomes a lot easier to achieve that. Programmers should be able to look at a function & tell if it is a ‘Command’ or a ‘Query’ knowing that error handling is not part of the function signature in any way.

Programming Style Guide: Code Refactoring

One of the key attributes towards code that is readable and easy on the eyes is code that is split into appropriately sized pieces. Code refactoring is does exactly that. It is very easy to write a program as one big piece of code. Of course, any program that grows becomes increasingly complicated and highly inefficient. If not controlled, it will soon reach a point where it is highly unreadable, extremely difficult to maintain & filled with bugs. Not to mention that it is inefficient too.

Refactoring code and breaking it down into smaller reusable chunks is the key. The objective is:

  1. To make code easier to read
  2. To make reusable components so that we can save on duplication of code. This will reduce the code count and make sure that any changes to the reused code are available everywhere.
  3. To lend a structure to the application. Tasks now have their own space.
  4. Build scalable and maintainable code.
  5. Build bug free code.

Let us look at an example.

Screen Shot 2017-10-16 at 11.26.26 AM

Bad Code

This code is clearly written poorly. Its difficult to read. There aren’t good whitespaces. No consistency. Even the naming conventions are poor.

The fix would be :

  • Break it down into different functions
  • Separate tasks into their own files
  • Name the different elements of the code properly.

This is how the code looks now. It has been broken down into different files.

main.cpp

#include <iostream>
#include "MathOperations.hpp"
#include "Choices.hpp"

int main(int argc, const char * argv[])
{
     float number1           = 0.0;
     float number2           = 0.0;
     Choices selectedOption  = CLEAR;
     float answer            = 0;
     float integralAnswer    = 0;

     while(EXIT != selectedOption)
     {
          //Welcome message
          std::cout<<"Welcome to Calculator Program"<<std::endl;
          std::cout<<"Choose between the following options"<<std::endl;
          std::cout<<"1. Add\n2. Subtract\n3. Multiply\n4. Divide\n5. Remainder\n6. Percentage"<<std::endl;

          //User choice
          std::cout<<"Choice: ";                               std::cin>>selectedOption;

          //Chance to enter first number
          std::cout<<"Number 1: ";                               std::cin>>number1;

          //Chance to enter second number
          std::cout<<"Number 2: ";                               std::cin>>number2;

          switch (selectedOption)
          {
               case ADDITION:
                    answer = addition(number1, number2);
                    std::cout<<"The addition of "<<number1<<" & "<<number2<<" = "<<answer<<std::endl;
                    break;
               case SUBTRACTION:
                    answer = subtraction(number1, number2);
                    std::cout<<"The subtraction of "<<number1<<" & "<<number2<<" = "<<answer<<std::endl;
                    break;
               case MULTIPLICATION:
                    answer = multiplication(number1, number2);
                    std::cout<<"The multiplication of "<<number1<<" & "<<number2<<" = "<<answer<<std::endl;
                    break;
               case DIVISION:
                    answer = division(number1, number2);
                    std::cout<<"The division of "<<number1<<" & "<<number2<<" = "<<answer<<std::endl;
                    break;
               case REMAINDER:
                    integralAnswer = remainder((int)number1, (int)number2);
                    std::cout<<"The remainder of "<<number1<<" divided by "<<number2<<" = "<<integralAnswer<<std::endl;
                    break;
               case PERCENTAGE:
                    answer = percentage(number1, number2);
                    std::cout<<"The percentage of "<<number1<<" out of "<<number2<<" = "<<answer<<span 				data-mce-type="bookmark" 				id="mce_SELREST_start" 				data-mce-style="overflow:hidden;line-height:0" 				style="overflow:hidden;line-height:0" 			></span><std::endl;
                    break;
               default:
                    break;
          }
     }
     return 0;
}

Choices.hpp

#ifndef Choices_hpp
#define Choices_hpp

#include <stdio.h>
#include <iostream>

enum Choices : unsigned short int { ADDITION = 1, SUBTRACTION, MULTIPLICATION, DIVISION, REMAINDER, PERCENTAGE, CLEAR, EXIT};

typedef enum Choices Choices;

std::istream& operator >>(std::istream &is, Choices& enumVar);

#endif

Choices.cpp

#include "Choices.hpp"

std::istream& operator >>(std::istream &is, Choices& enumVar)
{
    unsigned short int intVal;
    is>>intVal;
    switch (intVal) {
        case 1:
            enumVar = ADDITION;
            break;
        case 2:
            enumVar = SUBTRACTION;
            break;
        case 3:
            enumVar = MULTIPLICATION;
            break;
        case 4:
            enumVar = DIVISION;
            break;
        case 5:
            enumVar = REMAINDER;
            break;
        case 6:
            enumVar = PERCENTAGE;
            break;
        default:
            enumVar = EXIT;
            break;
    }
    return is;
}

MathOperations.hpp

#ifndef MathOperations_hpp
#define MathOperations_hpp

#include <stdio.h>

//Addition
float addition(float number1, float number2);

//Subtraction
float subtraction(float number1, float number2);

//Multiplication
float multiplication(   float number1, float number2);

//Division
float division(float number1, float number2);

//Remainder
int remainder(int number1, int number2);

//Percentage
float percentage(float number1, float number2);

#endif

MathOperations.cpp

#include "MathOperations.hpp"

//Addition
float addition(float number1, float number2)
{
    return number1 + number2;
}

//Subtraction
float subtraction(float number1, float number2)
{
    return number1 - number2;
}

//Multiplication
float multiplication(   float number1, float number2)
{
    return number2 * number1;
}

//Division
float division(float number1, float number2)
{
    if (number2 > 0) {
        return number1 / number2;
    }
    return 0.0;
}

//Remainder
int remainder(int number1, int number2)
{
    return number1 % number2;
}

//Percentage
float percentage(float number1, float number2)
{
    if (number2 > 0) {
        return (number1 / number2) * 100.0;
    }
    return 0.0;
}

Let us look at how this looks for Swift.
main.swift

import Foundation

var number1 : Float             = 0.0
var number2 : Float             = 0.0
var selectedOption : Choices    = Choices.CLEAR
var answer : Float              = 0.0
var integralAnswer : Int        = 0

func readNumbers(One firstNumber : inout Float, Two secondNumber : inout Float)
{
     //Chance to enter first number
     print("Number 1: \n")
     firstNumber = Choices.inputNumbers()

     //Chance to enter second number
     print("Number 2: \n")
     secondNumber = Choices.inputNumbers()
}

while(Choices.EXIT != selectedOption)
{
     //Welcome message
     print("Welcome to Calculator Program")
     print("Choose between the following options")
     print("1. Add\n2. Subtract\n3. Multiply\n4. Divide\n5. Remainder\n6. Percentage")

     //User choice
     print("Choice: \n")
     selectedOption = Choices.inputChoices()
     switch (selectedOption)
     {
          case Choices.ADDITION:
               readNumbers(One: &number1, Two: &number2)
               answer = addition_of(_value: number1, with_value: number2)
               print("The addition of \(number1) & \(number2) = \(answer)")
               break
          case Choices.SUBTRACTION:
               readNumbers(One: &number1, Two: &number2)
               answer = subtraction_of(_value: number1, from_value: number2)
               print("The subtraction of \(number1) & \(number2) = \(answer)")
               break
          case Choices.MULTIPLICATION:
               readNumbers(One: &number1, Two: &number2)
               answer = multiplication_of(_value: number1, with_value: number2)
               print("The multiplication of \(number1) & \(number2) = \(answer)")
               break
          case Choices.DIVISION:
               readNumbers(One: &number1, Two: &number2)
               answer = division_of(_value: number1, by_value: number2)
               print("The division of \(number1) & \(number2) = \(answer)")
               break
          case Choices.REMAINDER:
               readNumbers(One: &number1, Two: &number2)
               integralAnswer = remainder_of(_value: Int(exactly:number1)!, <span 				data-mce-type="bookmark" 				id="mce_SELREST_start" 				data-mce-style="overflow:hidden;line-height:0" 				style="overflow:hidden;line-height:0" 			></span>divided_by_value: Int(exactly: number2)!)
               print("The remainder of \(number1) divided by \(number2) = \(integralAnswer)")
               break
          case Choices.PERCENTAGE:
               readNumbers(One: &number1, Two: &number2)
               answer = percentage_of(_value: number1, with_respect_to_value: number2)
               print("The percentage of \(number1) out of \(number2) = \(answer)")
               break
          default:
               selectedOption = .EXIT
               break
     }
}

Choices.swift

import Foundation

enum Choices { case ADDITION, SUBTRACTION, MULTIPLICATION, DIVISION, REMAINDER, PERCENTAGE, CLEAR, EXIT}

//CLI Reading Capability
extension Choices
{
    static func inputChoices() -> Choices
    {
        let ip : String? = readLine()
        let choice : String = String(ip!)

        switch choice {
        case "1":
            return .ADDITION
        case "2":
            return .SUBTRACTION
        case "3":
            return .MULTIPLICATION
        case "4":
            return .DIVISION
        case "5":
            return .REMAINDER
        case "6":
            return .PERCENTAGE
        default:
            return .EXIT
        }
    }

    static func inputNumbers() -> Float
    {
        let ip : String? = readLine()

        let numberFormatter = NumberFormatter()
        let number = numberFormatter.number(from: ip!)

        let num : Float? = number?.floatValue
        return num!
    }
}

MathOperations.swift

import Foundation

//Addition
func addition_of(_value number1 : Float, with_value number2 : Float) -> Float
{
    return number1 + number2;
}

//Subtraction
func subtraction_of(_value number2 : Float, from_value number1 : Float) -> Float
{
    return number1 - number2;
}

//Multiplication
func multiplication_of(_value number1 : Float, with_value number2 : Float) -> Float
{
    return number2 * number1;
}

//Division
func division_of(_value number1 : Float, by_value number2 : Float) -> Float
{
    if (number2 > 0) {
        return number1 / number2;
    }
    return 0.0;
}

//Remainder
func remainder_of(_value number1 : Int, divided_by_value number2 : Int) -> Int
{
    return number1 % number2;
}

//Percentage
func percentage_of(_value number1 : Float, with_respect_to_value number2 : Float) -> Float
{
    if (number2 > 0) {
        return (number1 / number2) * 100.0;
    }
    return 0.0;
}

Discussion on Swift Extensions

As we can see that most of the code in Swift is very similar to C++. Most of the differences are basic syntactic differences. However, there is 1 feature of Swift that greatly aids code refactoring that I would like to talk about, Extensions.

Extensions allow us to add new functionality to the existing type. As the name says the type is extended. This allows us to add changes to a type in a consistent & clearly demarcated way. Developers can now neatly separate newly added components. This greatly helps in understanding the evolution of types.

“This is often referred to as versioning.”

Extensions can be used in the following ways to implement code refactoring:

  • Different sections of a type reside in their own extensions
  • Changes made to a type are made by keeping them in their own extensions
  • Step by step build up of code is done by representing each step as an independent extension. This gives clarity on how a certain end result was achieved.

Conclusion

As we can see from the sample code above (for both C++ & Swift) the program is much more readable. Code is carefully compartmentalised. Its a lot easier to read. It is a lot easier to scale too.

The reader may point out that the amount of code to achieve the same result is significantly higher, that however is a small price to pay in the long run. The biggest advantage is the scalability & the ease with which it can be done. Simply breaking code down into separate files & functions makes a huge difference. Here are some other benefits:

  • Individual files can be modified. This means one can now have a team working on different parts of the code.
  • Code is less cluttered. Changes are now spread across files & are easier to track.

We will now see how we can further improve this code in upcoming articles.