Lately I started working on a new project at work. We just started laying the foundation for everything and I ran into the problem of how to assign general responsibilities to various components in the code so that we establish some sorts of patterns and standards used everywhere in the code. Some roles and functionalities were already defined, I found this really useful so I decided to write this post. I still have a lot of things to learn.
Having an uniform code with a similar structure everywhere makes it really easy to understand. Also having clearly assigned roles to objects makes it easier to understand.
1. "Calculator" functionality
If you have a class in which you do some kind of mathematical calculations and comparisons then you should add this in the class name. In general it encompasses some kind of mathematical formula. For example at one point I had to calculate how much fluid I had to allocate for some tubes. In general when you deal with numbers, you will run into these components. I think financial applications will have many of these sort of components.
2. "Source" functionality
If you need some kind of information/data like settings or translations from a various sources then you can just add "source" objects/classes. I saw this role even in some of the functionalities of the .Net framework itself. For example in .Net core, there are various configuration sources for configuration settings like json files or environment variables. If you are using Windows Presentation Foundation, ListView components has the "ItemsSource" property;
3. "Selector"/"Router" functionality
I saw this one recently. It pretty much means a component that takes as a parameter a context, analyzes it and then determines what action to execute next. Usually it just returns another component which represents the action to execute. The best example of this kind of functionality the actual routing functionality in Asp .Net MVC Core. The routing functionality selects the method and the controller to be executed when a HTTP request is received. By no coincidence, the routing functionality uses the HttpContext as a parameter to determine what action to execute next, notice the "context" word in the "HttpContext" class name.
4. "Context" functionality
This responsibility is usually found when you need to execute an action in a wider scope. This scope can influence how the action is executed. Usually this action is just one in a series of actions that all need to share one scope. This "scope" is the actual context of the actions. Each action can modify and change the scope. So through the scope, each action can influence other future actions or even stop them from being executed. For example, earlier I mentioned about the HttpContext class in Asp .Net Core. This class actually has a couple of components, the Request and the Response. The Request component contains information about the request that the browser send to the Asp .Net server and the Response component contains the result that is built by the processing pipeline to be sent back to the browser. Now this processing pipeline is composed of a chain of actions called "middlewares", not really intuitive for my tastes. Each of these actions executes itself based on the HttpContext.
5. "Filter" functionality
This one is usually used when you have a collection of some kind of data and you need to extract only specific information from that collection. Usually it has a method that takes as a parameters the target collection of data objects to filter and returns another collection of filtered objects. Notice here that it is a good practice not to modify the original collection because it might be used in other places which need the original unfiltered data objects.
Or it can mean when you need to restrict some actions from being executed based on a criteria, like the filter functionality from Asp .Net Core.
6. "Modifier" functionality
This one adds a new level of indirection between objects which contain data and changes to those objects. Instead of actually changing the original data objects, a new object is generated which encompass the changes to the data object. This newly generated object has a method which takes a data object as a parameter, and returns a new object of the same type as the original data object but with the required changes applied to it. These separate objects responsible for changes are usually stored in a stack. Optionally, these change objects can have a "Apply" and "Remove" methods. In this case, the data object is modified directly instead of creating a new one, because the "Remove" method can restore the original state of the method. Their sole purpose is to modify the data in a very specific way and nothing more. Their only scope is the data to modify. They are usually chained one after another in a stack or list, and the most recent state of the data is found at the top of the stack. Their order is not predetermined and the same is for the number of modifiers.
This functionality is usually used when the end user needs to edit complex objects and he needs to revert the changes in various circumstances in case he is not happy with them. Text editors and IDEs have this functionality because developers need to revert changes up to a point quite often. Also in 3D programs this is pretty much standard and deeply integrated in the modeling, rigging and animation workflows.
It's a bit similar to the "pipeline" functionality but in the pipeline the actions are more complex and more predetermined, have more responsibilities and a bigger scope.
7. "Pipeline" functionality
A pipeline is a series of several step objects that usually take a context object and execute actions based on it. These steps have a specific order which is very important. Changing the order of the steps can cause crashes. There are some dependencies between these steps. Usually the pipeline is fixed and rarely changes during the runtime of the application.
Webservers and web frameworks usually have these sort of pipelines defined in them but they are usually hidden and not really obvious. You will never see the name "step" directly but rather something similar to module, run or actions. These actions are defined when the server starts and when a request arrives, a new series of action objects are defined which process that request.
Compared to the "modifier" functionality mentioned earlier, the scope of the actions in the pipeline is bigger compared to modifiers. These actions usually touch external systems such as databases, other web services and so on.
In the old Asp .Net these actions where called HttpModule or HttpHandler. In Asp .Net MVC core they are kind of nonintuitively called "Middlware". The name suggests that they are somewhere in the middle but they can be anywhere in the processing pipeline, at the beginning or the end.
Usually these pipeline actions do things like initialize the web request session, authenticate or authorize the request, log the request, audit the request and so on.
8. "Attribute" functionality
This functionality is used when there are too many various properties needed on objects that would make the class definition of that object just too big. And for some reason in certain circumstances, users of the application want to attach dynamically new custom properties to an object which are not known ahead of time or can change quite often. Because of this, properties can't be added in the class definition of an object during the development process. So inside the class definition, a collection of custom defined attributes is declared. Usually an attribute is defined by 2 important fields/properties: the name/ID of that property and the actual value of that attribute.
Usually this is coupled with database support where there exists a separate table linked to the main table in which the objects are stored. This table stores the custom attributes and usually has a structure similar to the attribute class, with at least 2 columns, one for the attribute name/ID and another one for the attribute value.
Also there is another table which contain a list of all the possible attribute types which has at least 2 columns usually: the ID column and the name column. Or it can have just one column, name used as an ID too.
9. "Manager" functionality
This one is a bit tricky and often quite misused and overused. It's actual meaning is quite vague a lot of times and hard to understand. This is why it's misused. In general the manager manages big tasks and processes that usually take a while to execute. These tasks and processes have a pretty complex life cycle with various states such as finished, processing, starting, stopping and so on. The manager can check these tasks if they have finished properly, if they have failed and take actions accordingly such as retrying them at a later time. Now what are these big tasks? They can be various pipelines mentioned above or even separate processes and application on other machines. It keeps them grouped together and organized in a single place. Usually there are just a few of these managers in applications. They can take requests to start new tasks, stop existing ones and so on. It also schedules tasks to start when resources become available, when other tasks have finished processing. And in general it takes a bit of time to setup a new task or to stop an existing task.
But a lot of people disagree with these managers and avoid them in code at all costs. I used them and never had any troubles. I can't figure out if they are really good or bad. Also it is being rendered useless in some circumstances by the "Task" and asynchronous functionalities integrated in the .Net framework.
10. "Toggle" functionality
This functionality has the role of enabling and disabling other functionalities and features. Usually there is a toggle for each functionality and there is a toggle source which tells the toggles what functionality to enable or disable. There can be also multiple sources with predetermined priorities. Usually these sources can be configuration files or environment variables. Most of the times when a toggle is enabled or disabled, the corresponding user interface for the feature managed by the toggle is hidden and disabled.
11. "Validator" functionality
Usually when objects/classes contain data, it should be ensured that the data is valid. So for each object class, there can exist several validator classes/objects which check if the data of the object is valid. There can be several validators for one object type, checking various bits and pieces of the object.
The results of these validators are stored somewhere and usually in case of errors, message are stored in a list.
These all just some of the functionalities that I frequently encountered while I developed applications and websites. Most of these can work together at various levels. For example a task manager can manage the processing of some kind of requests. These processes can be composed of pipelines themselves.
Usually when a new software project starts or during the development of the software project, a series of common functionalities are defined for the entire project similar to the ones mentioned above. Usually a standard naming scheme is also defined for the functionalities which do similar things. Having a standard way of doing things makes the code easier to understand and read. So it's important to keep this in mind. In the end this become something like common sense in the project which everyone understands.
Having an uniform code with a similar structure everywhere makes it really easy to understand. Also having clearly assigned roles to objects makes it easier to understand.
1. "Calculator" functionality
If you have a class in which you do some kind of mathematical calculations and comparisons then you should add this in the class name. In general it encompasses some kind of mathematical formula. For example at one point I had to calculate how much fluid I had to allocate for some tubes. In general when you deal with numbers, you will run into these components. I think financial applications will have many of these sort of components.
2. "Source" functionality
If you need some kind of information/data like settings or translations from a various sources then you can just add "source" objects/classes. I saw this role even in some of the functionalities of the .Net framework itself. For example in .Net core, there are various configuration sources for configuration settings like json files or environment variables. If you are using Windows Presentation Foundation, ListView components has the "ItemsSource" property;
3. "Selector"/"Router" functionality
I saw this one recently. It pretty much means a component that takes as a parameter a context, analyzes it and then determines what action to execute next. Usually it just returns another component which represents the action to execute. The best example of this kind of functionality the actual routing functionality in Asp .Net MVC Core. The routing functionality selects the method and the controller to be executed when a HTTP request is received. By no coincidence, the routing functionality uses the HttpContext as a parameter to determine what action to execute next, notice the "context" word in the "HttpContext" class name.
4. "Context" functionality
This responsibility is usually found when you need to execute an action in a wider scope. This scope can influence how the action is executed. Usually this action is just one in a series of actions that all need to share one scope. This "scope" is the actual context of the actions. Each action can modify and change the scope. So through the scope, each action can influence other future actions or even stop them from being executed. For example, earlier I mentioned about the HttpContext class in Asp .Net Core. This class actually has a couple of components, the Request and the Response. The Request component contains information about the request that the browser send to the Asp .Net server and the Response component contains the result that is built by the processing pipeline to be sent back to the browser. Now this processing pipeline is composed of a chain of actions called "middlewares", not really intuitive for my tastes. Each of these actions executes itself based on the HttpContext.
5. "Filter" functionality
This one is usually used when you have a collection of some kind of data and you need to extract only specific information from that collection. Usually it has a method that takes as a parameters the target collection of data objects to filter and returns another collection of filtered objects. Notice here that it is a good practice not to modify the original collection because it might be used in other places which need the original unfiltered data objects.
Or it can mean when you need to restrict some actions from being executed based on a criteria, like the filter functionality from Asp .Net Core.
6. "Modifier" functionality
This one adds a new level of indirection between objects which contain data and changes to those objects. Instead of actually changing the original data objects, a new object is generated which encompass the changes to the data object. This newly generated object has a method which takes a data object as a parameter, and returns a new object of the same type as the original data object but with the required changes applied to it. These separate objects responsible for changes are usually stored in a stack. Optionally, these change objects can have a "Apply" and "Remove" methods. In this case, the data object is modified directly instead of creating a new one, because the "Remove" method can restore the original state of the method. Their sole purpose is to modify the data in a very specific way and nothing more. Their only scope is the data to modify. They are usually chained one after another in a stack or list, and the most recent state of the data is found at the top of the stack. Their order is not predetermined and the same is for the number of modifiers.
This functionality is usually used when the end user needs to edit complex objects and he needs to revert the changes in various circumstances in case he is not happy with them. Text editors and IDEs have this functionality because developers need to revert changes up to a point quite often. Also in 3D programs this is pretty much standard and deeply integrated in the modeling, rigging and animation workflows.
It's a bit similar to the "pipeline" functionality but in the pipeline the actions are more complex and more predetermined, have more responsibilities and a bigger scope.
7. "Pipeline" functionality
A pipeline is a series of several step objects that usually take a context object and execute actions based on it. These steps have a specific order which is very important. Changing the order of the steps can cause crashes. There are some dependencies between these steps. Usually the pipeline is fixed and rarely changes during the runtime of the application.
Webservers and web frameworks usually have these sort of pipelines defined in them but they are usually hidden and not really obvious. You will never see the name "step" directly but rather something similar to module, run or actions. These actions are defined when the server starts and when a request arrives, a new series of action objects are defined which process that request.
Compared to the "modifier" functionality mentioned earlier, the scope of the actions in the pipeline is bigger compared to modifiers. These actions usually touch external systems such as databases, other web services and so on.
In the old Asp .Net these actions where called HttpModule or HttpHandler. In Asp .Net MVC core they are kind of nonintuitively called "Middlware". The name suggests that they are somewhere in the middle but they can be anywhere in the processing pipeline, at the beginning or the end.
Usually these pipeline actions do things like initialize the web request session, authenticate or authorize the request, log the request, audit the request and so on.
8. "Attribute" functionality
This functionality is used when there are too many various properties needed on objects that would make the class definition of that object just too big. And for some reason in certain circumstances, users of the application want to attach dynamically new custom properties to an object which are not known ahead of time or can change quite often. Because of this, properties can't be added in the class definition of an object during the development process. So inside the class definition, a collection of custom defined attributes is declared. Usually an attribute is defined by 2 important fields/properties: the name/ID of that property and the actual value of that attribute.
Usually this is coupled with database support where there exists a separate table linked to the main table in which the objects are stored. This table stores the custom attributes and usually has a structure similar to the attribute class, with at least 2 columns, one for the attribute name/ID and another one for the attribute value.
Also there is another table which contain a list of all the possible attribute types which has at least 2 columns usually: the ID column and the name column. Or it can have just one column, name used as an ID too.
9. "Manager" functionality
This one is a bit tricky and often quite misused and overused. It's actual meaning is quite vague a lot of times and hard to understand. This is why it's misused. In general the manager manages big tasks and processes that usually take a while to execute. These tasks and processes have a pretty complex life cycle with various states such as finished, processing, starting, stopping and so on. The manager can check these tasks if they have finished properly, if they have failed and take actions accordingly such as retrying them at a later time. Now what are these big tasks? They can be various pipelines mentioned above or even separate processes and application on other machines. It keeps them grouped together and organized in a single place. Usually there are just a few of these managers in applications. They can take requests to start new tasks, stop existing ones and so on. It also schedules tasks to start when resources become available, when other tasks have finished processing. And in general it takes a bit of time to setup a new task or to stop an existing task.
But a lot of people disagree with these managers and avoid them in code at all costs. I used them and never had any troubles. I can't figure out if they are really good or bad. Also it is being rendered useless in some circumstances by the "Task" and asynchronous functionalities integrated in the .Net framework.
10. "Toggle" functionality
This functionality has the role of enabling and disabling other functionalities and features. Usually there is a toggle for each functionality and there is a toggle source which tells the toggles what functionality to enable or disable. There can be also multiple sources with predetermined priorities. Usually these sources can be configuration files or environment variables. Most of the times when a toggle is enabled or disabled, the corresponding user interface for the feature managed by the toggle is hidden and disabled.
11. "Validator" functionality
Usually when objects/classes contain data, it should be ensured that the data is valid. So for each object class, there can exist several validator classes/objects which check if the data of the object is valid. There can be several validators for one object type, checking various bits and pieces of the object.
The results of these validators are stored somewhere and usually in case of errors, message are stored in a list.
These all just some of the functionalities that I frequently encountered while I developed applications and websites. Most of these can work together at various levels. For example a task manager can manage the processing of some kind of requests. These processes can be composed of pipelines themselves.
Usually when a new software project starts or during the development of the software project, a series of common functionalities are defined for the entire project similar to the ones mentioned above. Usually a standard naming scheme is also defined for the functionalities which do similar things. Having a standard way of doing things makes the code easier to understand and read. So it's important to keep this in mind. In the end this become something like common sense in the project which everyone understands.
Comments
Post a Comment