What is the purpose of enclosing all return values and arguments of a method in separate classes?

Question

I've seen such a convention. Whenever a public method is declared, two classes are also defined that enclose its return value and parameters like this:

public MethodNameReturnDTO MethodName(MethodNameParametersDTO parameters)
{
    // method body
}

public class MethodNameParametersDTO
{
    // blah
}

public class MethodNameReturnDTO
{
    // blah
}

This is the case even if one of the above classes has no fields or properties.

What is the purpose of doing so? What are its pros and cons?

On the first glance I can only see cons, but it is very possible I'm missing something.

NB: Tagging this question C# because this is where I saw this convention, but I guess this Q could be tagged language agnostic just as well? Idk.

Answer 1

Whether it's a widespread convention (I hope it's not), I don't know, but I agree with @Telastyn—see their answer. Those are the same reason why many people keep naming classes with DTO.

I will ignore the DTO thing on purpose and focus on reasons to encapsulate inputs and outputs.

What is the purpose of doing so?

Above all, expressiveness. Allow me to use Message and Receipt to elaborate on this point and the following ones.

boolean send(string subject, string body, string target, string[] cc, boolean isHtml) 
//and 
Receipt send(message)

Which one do you think causes less cognitive load?

Thought work, next time you speak to a coworker about messages instead of messages, say string subject, string body, string target, string[] cc, boolean isHtml. After a while, get back to message and note if you feel somewhat "released".

This is a naive example of course, but try to apply this rationale to your current project. Make your code to be readen in the same "ubiquitous" language you speak when talking about the business or the domain you are modelling.

Other purposes

1. Abstraction.

   The definition of a Message can change over time. The same rationale applies to the response Receipt. Changes can be motivated by new requirements. For example, supporting different channels (email, SMS, cloud notifications, event-driven communications, etc.)

2. Encapsulation and Data consistency.

   You tie up information that shares the same lifecycle. The information is validated, consumed and discarded together as a single unit of information. The correctness/consistency of these units must be ensured at the same time and in the same place.

3. Testing

   If you need to test logic based on the Message or Receipt state (isValid() or isSent() or acknowledged()), the only points to tackle/mock are those two elements. That can be complicated if Receipt is more than a single flag or Messages has different states (created, sending, pending, awaiting ack, rejected, accepted, deleted)

What are its pros and cons?

I have listed some of the pros. But, as usual, the pros and cons are contextual. Those are "pros" only when they are relevant to you and that's contextual. It changes or evolves.

The cons are inherent to the cons of over-engineering, being complexity the most important one. Unnecessary complexity to be precise. Unnecessary complexity is followed by code harder / more expensive to maintain. Another con derives from abstractions not backed by facts (reasons to exist). These abstractions with no clear direction or focus are candidates to become a sort of fit-all-solution. Ultra generic/abstract designs bring the seed of evil.

---

^{1: For example, if we narrow the context to MVC's controllers or REST controllers/clients we wouldn't see much inconvenience.}

Answer 2

What is the purpose of doing so?

Potentially, it allows you to violate the open closed principle and add things to these DTOs without impacting the rest of the code as much. It also potentially satisfies some arbitrary coding standard, or some terrible generic abstract class that needs generic parameters for its inputs and outputs.

Occasionally, this is the result of code generation. If an API is defined in something like Thrift, these input/output classes are generated based on that. Most codegen tools would be smart enough not to generate empty classes, but not all.

Mostly though, it is some foolish dogma that people follow because they’re “supposed to”. If your function has too many arguments, hiding them within an aggregation structure doesn’t reduce coupling or complexity.

Answer 3

Mainly, it comes down to readability and maintainability. For example, let's say that you're using a method to create a new user, and this method can accept the first name, last name, email, username, street, city, state, postal code, country, preferred language, preferred currency, and a dozen other properties. Even if you have some kind of auto-complete hinting system, you now have to decide how you're going to remember which parameter is which when you decide to add a new property, which leads to something like:

String firstName = 'First';
String lastName = 'Last';
String email = 'example@example.com';
String username = 'username';
String street = 'Street';
String city = 'City';
String state = 'State';
String postalCode = '12345';
String country = 'US';
String language = 'en';
String locale = 'en_US';
String timezone = 'UTC';
String defaultApplication = 'Home';

UserDomain.createUser(
    firstName,
    lastName,
    email,
    username,
    street,
    city,
    state,
    postalCode,
    country,
    language,
    locale,
    timezone,
    defaultApplication
);

If this API ever changes, your code may break, because you can't guarantee the order is correct anymore. This increases maintenance requirements because you now need to remember a very long list of parameters.

In addition, some languages have a maximum number of parameters you can supply to a method. In the server-side language of Salesforce, the Apex Code runtime limits a method to 32 parameters. If you need more than that, you're now writing so-called "DTO" (Data Transfer Objects) classes to handle that data anyways. Further, most languages allow you to only return one return value. If the result may include multiple values (e.g. isSuccessful/errorMessage), it's also helpful to have such an object to represent this type of output.

You might liken this to the difference between a SOAP/RPC and REST endpoint. With SOAP or RPC, the parameters are always in order, and any deviation will result in a runtime error. In those situations, developers typically end up using some kind of DTO object anyways, which mitigates errors caused by revisions to the API. REST, by contrast, tends to use JSON. The great thing about JSON is the parameters are almost always wrapped up in an object anyways. The parameter values don't care about their order within the object (at least, in any sane implementation of JSON parsing).

However, if there are no properties to accept/return, I would state that this falls squarely in the YAGNI (You Ain't Gonna Need It) rule. If a method is designed to never return a value, it should be a void (or equivalent in the language) return type. Returning anything else increases cognitive load by suggesting that some type of return value is possible. Clear, concise code should strive to not increase cognitive load unnecessarily. Similarly for the input parameters, if there's no expected input, there should be no such parameter defined.

Personally, I'm against calling a class a DTO class unless it does, in fact, cross the wire from one device to another (typically client-server, but also possibly client-client or server-server). The name of the class and its context should be enough to explain the nature of the class. I would expect a User class to have the properties of a user. It may also have methods to manipulate that data, or that code might be in a domain layer that uses this object to deal with users; that should be clear from context.

So, the pros for a "DTO" class, whether or not it is called a DTO, is that it greatly improves maintainability and readability. While I could see an argument against such objects for literally one parameter, it really comes down to a design choice. When there is nothing to transfer in a given direction, there should be no parameters, or a void return type.

Answer 4

Although with a strong WEB framework you can parse HTTP requests into your parameter list without pain, there are still reasons why DTOs are preferred.

The pattern of data transfer objects is tailored to the nature of WEB APIs, where connections can be unstable, and the cost could be high. So, it's best to design wide APIs with many parameters and attach as much information as proper in the return value.

As a side effect, the signature of a WEB API is likely to grow very large, so you wrap them in DTOs for simplicity, at least at the first glance.

Personally, I recommend against DTOs for all WEB APIs. It's perfectly fine to have a few strings in the parameter list. However, I've seen some coding standards that require everything wrapped in a DTO. I would say they designed this for the sake of easy management.

Answer 5

Oh well. I feel like someone is overdoing it.

Let’s say you have an argument “name” of type string. It may be better to have a “name” type that may include first name, last name, and other things as needed. Gives you a proper abstraction. Makes sure to the compiler that “name” and “city” won’t be confused.

An abstraction for names is useful. An abstraction for “parameters passed to function x” or “return value of function x” isnt.

Answer 6

In most cases I think this is probably a bad convention, but there is one case I can think of where something like this is a good idea. If you use SignalR, the recommendation is to always use an object as a parameter for functions you call via SignalR and put all parameters for that function on the object.

The reason is that changing the parameters of a function is a breaking change and will cause any old client to throw errors if such a function is called with different arguments. But adding more properties to an object parameter is allowed and won't be a breaking change for older clients. So you can add more parameters to a function that way without breaking old clients that only understand the function with fewer parameters.

So if some kind of RPC and serialization is used with these functions, it could be that always using a class makes it easier to add parameters without making it a breaking change. But that depends heavily on the actual mechanism.

Answer 7

While I certainly wouldn't advocate always doing this, there are sometimes advantages to be gained by wrapping multiple parameters within an object, particularly if there is useful validation that can be done that would otherwise have to be done within the function body, cluttering up the actual functionality, e.g.

void ExecuteWithdrawal(WithdrawalInstruction instruction) {
  ... reduce account by amount instructed
}

class WithdrawalInstruction{
    ctor(string accountNumber, decimal withdrawalAmount){
        if (withdrawalAmount < 0) throw ArgumentException("...");
        if (!IsAccountNumberValid(accountNumber)) throw ArgumentException("etc");
        
        WithdrawalAmount = withdrawalAmount;
        AccountNumber = accountNumber;
    }
    decimal AccountNumber { get; }
    decmal WithdrawalAmount { get;}
}

Answer 8

From the same reason that distinguishes between using which or what questions.

Here is a different perspective:

    programming paradigms
        imperative: describes the process of getting the result
        declarative: describes the result

    programming paradigm sub sets
        imperative: procedural, object oriented
        declarative: functional, logic, mathematical, reactive

    programming languages

    programming techniques
        optimistic or asynchronous programming - succeed or re-try until succeed
        pessimistic or synchronous programming - prepare to succeed

Is “programming paradigm sub sets” the proper terminology? Is this summary close to reality? If not which or what are the differences?

Differently said enclosing all return values and arguments of a method in separate classes is a way to be prepared for unprepared.