Builder pattern methods

Throughout the code base there are many methods looking like builder pattern methods. I have three concerns with that:

1. Not all properties have corresponding builder methods. I’d suggest to make them mandatory, thus consistent, but it’s not the most important thing 😃
2. They are inconsistent in naming. MSBuildSetting has 3 different namings already (Set, With, and Use). I suggest to agree on a common naming, and change the existing methods (with a new major version; and maybe issue warnings upfront?!).
3. They are not returning a new object. Let me explain why returning a new instance is important/useful:
   • First, the builder pattern should work like that. So the status quo is a bit surprising.
   • Secondly, it supports use cases where a common instance is shared with multiple invocations of the same task

var commonNuGetPackSettings = new NuGetPackSettings {
    Authors = new[] { "..." },
    Owners = new[] { "..." },
    Symbols = true,
    BasePath = "...",
    OutputDirectory = "...",
    ... // many more
}
var firstPackageSettings = commonNuGetPackSettings
    .WithFiles(...);
var secondPackageSettings = commonNuGetPackSettings
    .WithFiles(...);

I hope this outlines the benefit good enough. It also applies to MSBuildSettings, for instance if you want to separate Compile from CodeAnalysis for reasons of parallelism. Please note that the builder pattern doesn’t necessarily require immutability.

[devlead]

@matkoch in general reasoning behind starting as an addin/module is that we can test & bake the API before we merge it into the main project. Addins can also be reved more quickly and in a safe way without risking bloating or creating unnecessary breaking changes in the core, And if it proves to be consensus around the API then we can pull in a fully baked API. This is especially good when weren’t 100% sure yet on value of refactoring.

[matkoch]

Sorry but I don’t understand 🤔 So far your response has been do it as an addin. But this doesn’t solve anything.

First, it doesn’t tackle the status quo. You’ve mentioned a stable API. At the same time you should ask yourself if you want to carry this burden with you. There will always be people asking:

Okay, this is called UseXXX, and that WithXXX… What’s the difference?

or more annoyingly

WithToolsVersion … ah fuck … UseToolVersion.

Breaking an API is per se nothing bad. You can always help fixing the problem early upfront by issuing warnings (ObsoleteAttribute). Plus - UseToolVersion as an example - there are usage counts of around 150 on GitHub. I think under those circumstances, changes are very acceptable.

Second and more importantly, it doesn’t encourage any guidelines for the future. Given the fact that addins can be created any time by any developer, we will always end up with inconsistencies. Again and again. And because there is no consistency, you’ll either never integrate any of them, or introduce breaking changes for those, who have been using the addins.

not introduce more … without thinking it through

Delegating to 3rd parties, doesn’t mean to think it through. After all, I’ve tried very hard to make this issue the place of thinking it through 😄