Skip to main content
Software Engineering

Return to Answer

Corrected to reflect that my criticism applied to the first approach proposed, not the second.
Source Link
combinatorics
combinatorics
  • 739
  • 1
  • 7
  • 8

From a DRY perspective

The second one is correct.

A common misunderstanding of DRY is that it applies to expressions of concepts, rather than to the concepts themselves.

This mostly seems to come from programmers being told that they shouldn't copy/paste things and thinking that means any sufficiently similar representations of concepts should be consolidated. This leads to people going on crusades in the codebase to rid it of any similar pieces of code. But this is wrong. When applying the SRP it's perfectly acceptable to have multiple classes containing essentially identical code as long as they are describing different system concepts.

In this case you've noticed that several system concepts (descriptions of methods) that can be expressed in a similar way. This is true, but by consolidating them you're mixing together multiple system concepts into a single, more complex, expression.

From a design perspective

Like any data structure the design of documentation depends on how you anticipate it will be updated and read. The downside of the secondfirst approach is that previously separate concepts are now mixed together in the documentation, which changes how they can be updated/read.

Consider the Single Responsibility Principle (SRP) here:

If any of those methods change their behaviour (unlikely in this specific case, but more likely in less platformy classes) it will require making a documentation change that will affect many classes. Changing the description of any one method is now harder because the updater will need to consider the impact of their change all the methods that the description applies to.

I would expect the most common operation will be someone looking up documentation for a method (rather than creating or updating). In that case it's a fair assumption they want be shown only the documentation relevant to that specific method, not other methods which happen to be similar. I certainly wouldn't want to have to look up tables and spent effort to disentangle the behaviour of other methods to get the information I want.

From a DRY perspective

The second one is correct.

A common misunderstanding of DRY is that it applies to expressions of concepts, rather than to the concepts themselves.

This mostly seems to come from programmers being told that they shouldn't copy/paste things and thinking that means any sufficiently similar representations of concepts should be consolidated. This leads to people going on crusades in the codebase to rid it of any similar pieces of code. But this is wrong. When applying the SRP it's perfectly acceptable to have multiple classes containing essentially identical code as long as they are describing different system concepts.

In this case you've noticed that several system concepts (descriptions of methods) that can be expressed in a similar way. This is true, but by consolidating them you're mixing together multiple system concepts into a single, more complex, expression.

From a design perspective

Like any data structure the design of documentation depends on how you anticipate it will be updated and read. The downside of the second approach is that previously separate concepts are now mixed together in the documentation, which changes how they can be updated/read.

Consider the Single Responsibility Principle (SRP) here:

If any of those methods change their behaviour (unlikely in this specific case, but more likely in less platformy classes) it will require making a documentation change that will affect many classes. Changing the description of any one method is now harder because the updater will need to consider the impact of their change all the methods that the description applies to.

I would expect the most common operation will be someone looking up documentation for a method (rather than creating or updating). In that case it's a fair assumption they want be shown only the documentation relevant to that specific method, not other methods which happen to be similar. I certainly wouldn't want to have to look up tables and spent effort to disentangle the behaviour of other methods to get the information I want.

From a DRY perspective

The second one is correct.

A common misunderstanding of DRY is that it applies to expressions of concepts, rather than to the concepts themselves.

This mostly seems to come from programmers being told that they shouldn't copy/paste things and thinking that means any sufficiently similar representations of concepts should be consolidated. This leads to people going on crusades in the codebase to rid it of any similar pieces of code. But this is wrong. When applying the SRP it's perfectly acceptable to have multiple classes containing essentially identical code as long as they are describing different system concepts.

In this case you've noticed that several system concepts (descriptions of methods) that can be expressed in a similar way. This is true, but by consolidating them you're mixing together multiple system concepts into a single, more complex, expression.

From a design perspective

Like any data structure the design of documentation depends on how you anticipate it will be updated and read. The downside of the first approach is that previously separate concepts are now mixed together in the documentation, which changes how they can be updated/read.

Consider the Single Responsibility Principle (SRP) here:

If any of those methods change their behaviour (unlikely in this specific case, but more likely in less platformy classes) it will require making a documentation change that will affect many classes. Changing the description of any one method is now harder because the updater will need to consider the impact of their change all the methods that the description applies to.

I would expect the most common operation will be someone looking up documentation for a method (rather than creating or updating). In that case it's a fair assumption they want be shown only the documentation relevant to that specific method, not other methods which happen to be similar. I certainly wouldn't want to have to look up tables and spent effort to disentangle the behaviour of other methods to get the information I want.

Source Link
combinatorics
combinatorics
  • 739
  • 1
  • 7
  • 8

From a DRY perspective

The second one is correct.

A common misunderstanding of DRY is that it applies to expressions of concepts, rather than to the concepts themselves.

This mostly seems to come from programmers being told that they shouldn't copy/paste things and thinking that means any sufficiently similar representations of concepts should be consolidated. This leads to people going on crusades in the codebase to rid it of any similar pieces of code. But this is wrong. When applying the SRP it's perfectly acceptable to have multiple classes containing essentially identical code as long as they are describing different system concepts.

In this case you've noticed that several system concepts (descriptions of methods) that can be expressed in a similar way. This is true, but by consolidating them you're mixing together multiple system concepts into a single, more complex, expression.

From a design perspective

Like any data structure the design of documentation depends on how you anticipate it will be updated and read. The downside of the second approach is that previously separate concepts are now mixed together in the documentation, which changes how they can be updated/read.

Consider the Single Responsibility Principle (SRP) here:

If any of those methods change their behaviour (unlikely in this specific case, but more likely in less platformy classes) it will require making a documentation change that will affect many classes. Changing the description of any one method is now harder because the updater will need to consider the impact of their change all the methods that the description applies to.

I would expect the most common operation will be someone looking up documentation for a method (rather than creating or updating). In that case it's a fair assumption they want be shown only the documentation relevant to that specific method, not other methods which happen to be similar. I certainly wouldn't want to have to look up tables and spent effort to disentangle the behaviour of other methods to get the information I want.