I'm going to ask your Point of view about a design matter.
The question is basically the following: a public method of an object should always check preconditions in its input parameters or is it better to love responsibility to the caller and "trust the flow" ?
I'm not talking about obvious preconditions such as checking for null to avoid null reference exceptions, but I'm referring to business preconditions in method parameters. This typical happens in DDD Services that perform some kind of validation on input parameters and return an object containing a feedback about that validation.
As an example consider a class CheckPerson having a public method PerformCheck with a single parameter of type Person. Imagine there is a business rule saying that this check doesn't make sense for blonde persons.
In my opinion this check is important and method name should reflect this rule (something like PerformCheckForNonBlondePerson).
Should I add these checks, or should I trust the caller?
Yes you should!
You need to differentiate between input validation and preconditions. Business rules, as you describe them, can be applied in both.
Input validation happens at the system boundary. You expect input validation to fail in some cases. When that happens, you should indicate the error to the client with a useful description of the error.
Preconditions, on the other hand, are part of the contract of a method (or a whole component) somewhere within your system. You always want to be sure this contract is adhered to, because your implementation will probably behave incorrectly otherwise. Here, we use guards to enforce the preconditions. A guard should always pass. If it does not, it is always a programmer error (as opposed to a user error).
#theDmi thanks for sharing your point of view.
I totally agree with your position.
The context when I'm currently working is a team of three people, implementing a large application with a good deal of business logic and domain rules to be taken into account.
The main reason I don't agree with the "trust the flow and delegate responsibility to the caller" philosophy is that this force every developer which is going to make a call to a domain service to explicitly read the code of such a service and to have a good knowledge about the business requirement behind that code.
In my opinion, this is not realistic and furthermore this is an error-prone process.
Domain layer in large application is called by every piece of application logic we are going to write and leaving all the responsibility to the caller is simply too dangerous in my opinion. We don't currently use any kind of library to enforce preconditions check, but I know there are several options out there :)
Related
I have a question regarding the "Use Case Output Port" in Uncle Bob´s Clean Architecture.
In the image, Uncle Bob describes the port as an interface. I am wondering if it has to be that way or if the invoked Use Case Interactor could also return a "simple" value. In either case the Application and Business Rules Layer would define its interface that the Interface Adapters Layer has to use. So I think for simple invocations just returning a value would not violate the architectural idea.
Is that true?
Additionally, I think this Output Port Interface implemented by the presenter should work like the Observer pattern. The presenter simply observes the interactor for relevant "events". In the case of .NET where events are first-class citizens, I think using one of these is the same idea.
Are these thoughts compatible with the ideas behind Clean Architecture?
Howzit OP. I see your question is still unanswered after all these years and I hope we can reason about this and provide some clarity. I also hope I am understanding your question correctly. So with that in mind, here is how I see the solution:
The short answer is, a use case interactor should be able to return a simple value (by which I assume string, int, bool etc) without breaking any architectural rules.
If we go over the onion architecture, which is very similar to the clean architecture, the idea is to encapsulate the core business logic in the center of the architecture, the domain. The corresponding concept in the clean architecture is the entities and the use cases on top of it. We do this because we want to dictate our understanding of the business in a consistent way when we write our business rules.
The interface adapters allow us to convert the outside world to our understanding. What we want is a contract in our domain (use cases or entities) that ensures we will get what we need from the outside world, without knowing any implementation details. We also don't care what the outside world calls it, we convert their understanding to ours.
A common way to do this, is to define the interface in the domain to establish a contract that says, we expect to give "x", and you must then tell us what "y" is. The implementation can then sit outside the domain.
Now to get to the core of your question. Let's assume that the core of our application is to track some complicated process with various stages. During one of these stages, we need to send data to a couple of external parties and we want to keep a reference of some sort for auditing purposes. In such a case our interface may sit in the domain and state we send our complicated object to some party, and we expect a string reference back. We can then use this string reference and fire some domain event etc. The implementation can sit completely outside of the domain and call external APIs and do it's thing, but our core domain is unaffected. Hence returning a simple value has no impact on the architecture. The reverse of the above scenario may also hold true. We can say that we have a reference id of some sort, and the outside world needs to return us our understanding of some object.
For the second part of your question. I would imagine it depends on the use case itself. If you present some idea out there and need to constantly react to it, domain events will get involved and you will have a structure very similar to the observer pattern. .NET encapsulates events very nicely and fits very well with clean architecture and Domain driven design.
Please let me know if the above makes sense or if I can clarify it in any way.
Let's say I have a polygon class. Its only private data is an array of points. Should the class be written assuming the array has at least 3 points, and the GUI or input part of the program makes sure there are three points? Or should the member functions test the data validity and return an error message if needed?
There are some good points in the other answers. I'll try and state them here:
Ultimately, the model is responsible for knowing if it is in a valid state or not.
The UI needs to be aware if the model is in a valid state.
The UI can protect the model from invalid states AND provide good user feedback by validating the inputs.
There are some challenges:
If the model and UI both have validation code, the result is either duplicated code in the model/UI or a split between between the model and UI of the validation responsibilities.
UI validation gets messy because some data fields depend on others. Imagine an application that collects zip code and state (for US postal addresses). If you change the state, do you want the UI to immediately pop a dialogue box that says "Invalid zip code"? No. That would be annoying. The UI should give the user a chance to put the model into a valid state.
Throwing exceptions to catch validation errors is a heavy-handed way of doing things. Usually, you will want something less obtrusive.
Here is what I like to do for complex validation:
Allow the user the enter invalid values.
Create a class called ValidationError that includes a human-readable description of a single validation error.
Provide model methods like getValidationErrors() and isValid().
Before committing any changes to the model, have the UI call isValid() and getValidationErrors(). If there are any validation errors, make the UI display the errors to the user. Prevent the user from continuing until the errors are fixed.
The advantages of this approach are:
- More control of validation. You can decide when and what you want to validate.
- Centralizes validation logic in the model. The UI is only responsible for getting and displaying errors generated by the model.
- Less risk of other other code making invalid changes to a model if the model calls isValid() before calling save/commit methods.
-No exception handlers.
Consider creating a ValidationRule class. Each rule contains the code to valid something and generate an error message if it is invalid. The ValidationRule class has a method validate(aModel). This is especially easy to do if your programming language supports closures or first-class functions.
This results in each model class can have a dynamic collection of ValidationRule objects it consults when isValid() or getValiationErrors() is called. Alternatively, use a visitor pattern so that the models are are completely decoupled from the validation. This is what I do in my validation frameworks.
In a distributed application where the model is not on the client, it is often wise to do some basic validation before sending changes to the server. The round-trip time between client and server can be pretty long and you don't want to send obviously invalid requests to the server.
Lastly, the validity of one object sometimes depends on data in a different object! In these situations I let validation rules accept multiple objects, and use the controller object (or I create a context object) to manage the validation at a less granular level.
GUI validation is just meant for user hint.
Model should be responsible for its own integrity, as data may come from different sources rather than user [e.g. a background sync].
IMHO, a well-designed class will always protect its invariants. Therefore, the class must validate and always ensure it's in a valid state.
The UI can do it too or just rely on the class.
Take a look at Mark Seemann's blog post here.
If the class is expected to have at least 3 points you have to ensure it through the class interface. One way to achieve this (the only and best, actually) is receiving the polygon's points in the class constructor parameters and throw an exception if the points are less than 3 (remember that in a good OOP design, exceptions must not be seen as errors, but as a violation of implicit contracts).
Then, you just have to keep unmodified the values of those points. Think as if they where "final" in Java. Remember that whatever makes your object a certain polygon amongst every conceivable possible polygon is never expected to be modified. For instance, if you assigned the points in the constructor, then those points should be preserved all through the object's lifecycle both in quantity and values.
Always recall the most pure definition of object in OOP: an object is a computational representation of a real life entity. If your object represents polygon P, then it should never change in order to represent another polygon or any other real life entity. And you must never create an object "Polygon" if it actually doesn't represent a real world polygon. And that is achieved only through class constructors.
Following these design guides, you'll never need to add code to validate your object is a polygon inside the Polygon class, since it is a true polygon in the object paradigm.
So do the try {} catch {} when creating the polygon and let the constructor throw a NotPolygonException if needed.
I'm having trouble wrapping my head around state-based functionality for an invoicing system we are currently building. The system will support calculation, manual approval, printing, and archiving of invoices.
At first I thought we should use the State Pattern to model this. An invoice would be the context, which delegates printing, archiving, etc. to its currently assigned state.
But this is obviously a bad idea, because the different states (created, approved, printed, archived) should not support the same operations. E.g., you shouldn't be able to print an invoice, which hasn't been approved before. Throwing exceptions for unsupported operations would be a violation of LSP. I found a general description of this problem here.
Does anybody have an idea, how to implement this appropriately?
PS: I'm aware that this might sound like some lame-ass homework assignment, but it's not; I need this for a real world system.
You're basically creating a workflow of application states, where at each state the available operations on an invoice change. The state pattern doesn't seem appropriate, but you can still use it if you also create some operations like boolean canPrint() that would have to be used before calling print(). print() would have a contract that allows throwing exceptions if canPrint() returns false. This way, subclasses wouldn't break that contract. Another option is to have a boolean tryPrint(), that will only print if it can, and return whether it printed.
But, if the states support mostly non-overlapping operations, then maybe the state pattern is not the solution. Take a step back and look for better ways, without trying to fit a specific pattern to your problem. One way is to create a separate class with the necessary operations for each "state": like CreatedInvoice, ApprovedInvoice, etc. These classes would only have the operations they support.
Chain of Responsibility Pattern might help you here.
Adding the how part and fixing the link.
There can be Calculator, Approver, Printer and Archiver classes which are handler classes. These can have processRequest() overridden from a parent abstract class. Invoice can be a class which is passed to each handler's processRequest() method. The advantage with using the pattern here is newer handlers can be added dynamically and chain links with sequence of handlers can be changed easily.
Whether the State Pattern is really appropriate to your situation is not certain, but if it's not, Liskov is not the reason. Throwing some sort of "invalid operation in current state" exception can be defined as possible and valid in the state interface, and then subclasses doing this do not violate LSP.
The classic example used for the State Pattern in the GoF Design Patterns book is a TCPConnection, which definitely has operations not supported or sensible in all states. You can't transmit on a closed connection, for example.
This is most certainly a language agnostic question and one that has bothered me for quite some time now. An example will probably help me explain the dilemma I am facing:
Let us say we have a method which is responsible for reading a file, populating a collection with some objects (which store information from the file), and then returning the collection...something like the following:
public List<SomeObject> loadConfiguration(String filename);
Let us also say that at the time of implementing this method, it would seem infeasible for the application to continue if the collection returned was empty (a size of 0). Now, the question is, should this validation (checking for an empty collection and perhaps the subsequent throwing of an exception) be done within the method? Or, should this methods sole responsibility be to perform the load of the file and ignore the task of validation, allowing validation to be done at some later stage outside of the method?
I guess the general question is: is it better to decouple the validation from the actual task being performed by a method? Will this make things, in general, easier at a later stage to change or build upon - in the case of my example above, it may be the case at a later stage where a different strategy is added to recover from the event of an empty collection being return from the 'loadConfiguration' method..... this would be difficult if the validation (and resulting exception) was being done in the method.
Perhaps I am being overly pedantic in the quest for some dogmatic answer, where instead it simply just relies on the context in which a method is being used. Anyhow, I would be very interested in seeing what others have to say regarding this.
Thanks all!
My recommendation is to stick to the single responsibility principle which says, in a nutshell, that each object should have 1 purpose. In this instance, your method has 3 purposes and then 4 if you count the validation aspect.
Here's my recommendation on how to handle this and how to provide a large amount of flexibility for future updates.
Keep your LoadConfig method
Have it call the a new method for reading the file.
Pass the previous method's return value to another method for loading the file into the collection.
Pass the object collection into some validation method.
Return the collection.
That's taking 1 method initially and breaking it into 4 with one calling 3 others. This should allow you to change pieces w/o having any impact on others.
Hope this helps
I guess the general question is: is it
better to decouple the validation from
the actual task being performed by a
method?
Yes. (At least if you really insist on answering such a general question – it’s always quite easy to find a counter-example.) If you keep both the parts of the solution separate, you can exchange, drop or reuse any of them. That’s a clear plus. Of course you must be careful not to jeopardize your object’s invariants by exposing the non-validating API, but I think you are aware of that. You’ll have to do some little extra typing, but that won’t hurt you.
I will answer your question by a question: do you want various validation methods for the product of your method ?
This is the same as the 'constructor' issue: is it better to raise an exception during the construction or initialize a void object and then call an 'init' method... you are sure to raise a debate here!
In general, I would recommend performing the validation as soon as possible: this is known as the Fail Fast which advocates that finding problems as soon as possible is better than delaying the detection since diagnosis is immediate while later you would have to revert the whole flow....
If you're not convinced, think of it this way: do you really want to write 3 lines every time you load a file ? (load, parse, validate) Well, that violates the DRY principle.
So, go agile there:
write your method with validation: it is responsible for loading a valid configuration (1)
if you ever need some parametrization, add it then (like a 'check' parameter, with a default value which preserves the old behavior of course)
(1) Of course, I don't advocate a single method to do all this at once... it's an organization matter: under the covers this method should call dedicated methods to organize the code :)
To deflect the question to a more basic one, each method should do as little as possible. So in your example, there should be a method that reads in the file, a method that extracts the necessary data from the file, another method to write that data to the collection, and another method that calls these methods. The validation can go in a separate method, or in one of the others, depending on where it makes the most sense.
private byte[] ReadFile(string fileSpec)
{
// code to read in file, and return contents
}
private FileData GetFileData(string fileContents)
{
// code to create FileData struct from file contents
}
private void FileDataCollection: Collection<FileData> { }
public void DoItAll (string fileSpec, FileDataCollection filDtaCol)
{
filDtaCol.Add(GetFileData(ReadFile(fileSpec)));
}
Add validation, verification to each of the methods as appropriate
You are designing an API and should not make any unnecessary assumptions about your client. A method should take only the information that it needs, return only the information requested, and only fail when it is unable to return a meaningful value.
So, with that in mind, if the configuration is loadable but empty, then returning an empty list seems correct to me. If your client has an application specific requirement to fail when provided an empty list, then it may do so, but future clients may not have that requirement. The loadConfiguration method itself should fail when it really fails, such as when it is unable to read or parse the file.
But you can continue to decouple your interface. For example, why must the configuration be stored in a file? Why can't I provide a URL, a row in a database, or a raw string containing the configuration data? Very few methods should take a file path as an argument since it binds them tightly to the local file system and makes them responsible for opening, reading, and closing files in addition to their core logic. Consider accepting an input stream as an alternative. Or if you want to allow for elaborate alternatives -- like data from a database -- consider accepting a ConfigurationReader interface or similar.
Methods should be highly cohesive ... that is single minded. So my opinion would be to separate the responsibilities as you have described. I sometimes feel tempted to say...it is just a short method so it does not matter...then I regret it 1.5 weeks later.
I think this depends on the case: If you could think of a scenario where you would use this method and it returned an empty list, and this would be okay, then I would not put the validation inside the method. But for e.g. a method which inserts data into a database which have to be validated (is the email address correct, has a name been specified, ... ) then it should be ok to put validation code inside the function and throw an exception.
Another alternative, not mentioned above, is to support Dependency Injection and have the method client inject a validator. This would allow the preservation of the "strong" Resource Acquisition Is Initialization principle, that is to say Any Object which Loads Successfully is Ready For Business (Matthieu's mention of Fail Fast is much the same notion).
It also allows a resource implementation class to create its own low-level validators which rely on the structure of the resource without exposing clients to implementation details unnecessarily, which can be useful when dealing with multiple disparate resource providers such as Ryan listed.
If I have a User class, and his account can be suspended by adding an entry to the suspensions table, which of these class/method signatures do you think is more appropriate?
User::suspend($reason, $expiryDate);
Suspension::add($userid, $reason, $expiryDate);
This is a simple example, but I have this kind of situation everywhere throughout my application. On one hand, I'd want to make it a method of the User object, since the action performed is directly related to that user object itself, but on the other hand making it a method on the suspension object seems a bit cleaner.
What do you think?
you suspend a user.
User.Suspend()
In your User.Suspend method, you can actually add them to your "suspension" table, or call your suspension object. This will lead to a cleaner interface since all you have to do is call the one method.
Its definitely up to you. OO design is very subjective. Here, it depends on whether you view suspension as a noun (a suspension) or a verb (to suspend). If the former, it likely becomes its own object with appropriate methods and attributes. If the latter, it becomes a set of related methods and attributes of the User object.
This brings up another issue: are you a minimalist? There are those that try to keep many, light classes as opposed to a few heavy ones.
Personally, I see cohesion/coupling as outweighing all those factors by orders of magnitude. Basically, for me, it would hinge upon whether other system entities need to know about suspensions without having a User object to query with. If so, the Suspension class would be born. If not, I would keep it as a part of the User class.
Well if adding a suspension is the only real action, I would go with the first option and make it an action carried out by the User class.
However, if you intend on making more functionality for Suspensions, I would consider creating a class like:
class SuspensionManager
suspendUser(....)
getSuspendedUser(...)
....
*This is my opinion is 100% debatable given that I don't know your entire code base/intention
I would say neither. But it really depends on how you view OOAD. I consider both User and Suspension classes have a single purpose. The User class has the responsiblity of holding information directly associated with a User (user table), and the Suspension class has the responsibility of holding information directly associated with a Suspension (suspension table). I would suggest making a UserSuspention class that has the responsibility of suspending a user.
This approach to OOAD is related to SOLID design principals. Having either the User or Suspension class be responsible for suspending a user would violate SRP (single responsibility principal)...since each class already has the responsibilty of maintaining information from their respective tables.
Your potential API may look like something below:
public class UserSuspension
{
public void SuspendUser(User user, Suspension suspension) { ... }
public void SuspendUser(Guid userId, string reason, DateTime expiryDate) { ... }
}
From these two options I would vote for Suspension::add(), if in fact this call would add an entry to the suspensions table. That way the effect that this call in the code has, in terms of the code itself (i.e. not the concepts represented by the code), would be clear: if I saw the code User::suspend(), I would expect it to modify a "suspended" flag for the User object, not modify something else in some other object.
On the other hand, in this particular instance, I think User::suspend() is more clear in general, so I would vote for it if it would mean that a suspended flag would be set for that User object, or if it would seem that way from the interface, i.e. if you wouldn't have to care where the suspension is stored since the interface of the User class would make it seem as if it's one of its properties.
This situation is very typical in web application design. It often becomes easier to deal with objects as being disconnected entities, as it saves you from having to retrieve objects to perform an operation for which you didn't really need the object.
The former is nicer from an OOP sense, the question is whether the performance impact of this would bother you:
User user = GetUser($userId); // unnecessary database hit?
user.suspend(reason, expiryDate);
I would be inclined to have an Account which linked the User and the Suspension
It depends.
This could be one of those scenarios where there isn't a definitely right answer. It will depend on how data will move through your system, as to whether it's of more benefit to view this relationship in a data-centric, or a user-centric model.
An old rule-of-thumb is to view objects as nouns and methods as verbs, when you're trying to model things. This would tend to suggest that User is an object, and suspend is an action you might perform.
Simple ? Not really.
Someone else might argue that it made more sense to describe the suspension as an 'AccountAction', and the application of the suspension as a verb. That might lead you to a model where various subclasses of an AccountAction have an applyTo method that acts on other object types.
You may need to apply your objects to an existing database schema, in which case you'll have to take into account how your persitance layer or ORM will interact with existing record structures.
Sometimes it's down to technology. OO can be implemented in subtly different ways across different language families and this too can influence the design. Some systems favour more solid inheritance graphs, other languages emphasise more loosely interconnected objects, passing messages around.
You need to be thinking through your design in terms of how you're going to want to interact with data and state. If you think about objects, as instances of classes, representing states of data, with behaviours that you will wish to invoke, you might find the nouns and verbs pattern falling out of the sentences that you use to describe the system.
As others have stated, it's very subjective.
Personally, I prefer the User::suspend() alternative simply because it allows me to implement (or change the implementation of) suspension whenever I like. It leaves all the suspension logic hidden behind the User interface.
I often times struggle with the same problem and what I do is I ask myself if this would make sense outside of the programming world. Would you ask ,in real life , a user to suspend him/herself? Would you ask a loan application to approve itself? If the answer is no, then there needs to a specialized authority/component/service that handles that and similar scenarios. In case of loan application, the approval should best be a part of loan approval service or loan specialist. If in your case, asking a user to suspend himself makes sense in the domain you're modeling then it should belong to the user. If not then, a service that handles user account suspension and similar user account level services may be a better place.