[Proposal]: Implicit parameters

[radrow]

Implicit Parameters

• [x] Proposed
• [ ] Prototype: Not Started
• [ ] Implementation: Not Started
• [ ] Specification: Not Started

Summary

This proposal introduces implicit parameters for C#. It is highly inspired by a feature of Scala known under this exact name, as well as similar solutions from other languages. In spite of that inspiration, the aim is to make the new functionality as simple as possible in order to avoid numerous flaws caused by overly complex Scala's design. The motivation is to increase clarity and comfort of writing and refactoring code that extensively passes environmental values through the stack.

Implicit parameters are syntactic sugar for function applications. The idea is to pass selected arguments to methods without necessarily mentioning them across the code, especially where it would be repetitive and unavoidable. Thus, instead of writing

Data FetchData(CancellationToken token) {
    var request  = MakeDataRequest(token);
    var service  = GetService("main", token);
    var response = service.Send(request, token);
    
    if(response.IsNotOk) {
        service = GetService("fallback", token);
        return service.Send(request, token).Data();
    }
    
    return response.Data();
}

MakeDataRequest(CancellationToken token);
GetService(string name, CancellationToken token);

One could simplify it to something like:

Data FetchData(implicit CancellationToken token) {
    var request  = MakeDataRequest();
    var service  = GetService("main");
    var response = service.Send(request);
    
    if(response.IsNotOk) {
        service = GetService("fallback");
        return service.Send(request).Data();
    }
    
    return response.Data();
}

MakeDataRequest(implicit CancellationToken token);
GetService(string name, implicit CancellationToken token);

Note that the cancellation token (token) is provided implicitly to every call that declares it as its implicit argument. While it still needs to be declared in the function signature, the application is handled automatically as long as there is a matching implicit value in the context.

A way to look at this feature is that it is a counterpart of the default parameters that are already a part of C#. In both concepts some arguments are supplied by the compiler instead of the programmer. The difference is where those arguments come from; to find the source of an implicit parameter you need to look at the calling function's signature, as opposed to the called function in case of the default parameters.

Motivation

Since it is just a "smart" syntactic sugar, this feature does not provide any new control flows or semantics that were not achievable before. What it offers is that it lets one write code in a certain style more conveniently, and with less of boilerplate.

The promoted paradigm is to handle environment and state by passing it through stack, instead of keeping them in global variables. There are numerous benefits of designing applications this way; most notably the ease of parallelization, test isolation, environment mocking, and broader control over method dependencies and side effects. This can play crucial role in big systems handling numerous tasks in parallel, where context separation is an important security and sanity factor.

Simple CancellationToken examples like the previous one are likely to be common. The following example is more elaborate, showing a realistic implementation of a gRPC server converting image files:

void CheckCancellation(implicit ServerCallContext ctx) =>
    ctx.CancellationToken.ThrowIfCancelled();

bool FileCached(string fileName, implicit ServerCallContext ctx) =>
    ctx.RequestHeaders.Get("use_cache") && Cache.Exists(fileName);

async Task ConvertJpgToPng(
  int fileSize,
  string fileName,
  implicit IAsyncStreamReader<Req> inStream,
  implicit IServerStreamWriter<Res> outStream,
  implicit ServerCallContext ctx)
{
    bool cached = FileCached(fileName); // !
    
    Jpg jpg = null;
    if(cached)
    {
        await RequestNoFile(); // !
        jpg = Cache.Get(fileName); // !
    }
    else
    {
        jpg = await RequestFile(); // !
    }
    CheckCancellation(); // !
    
    Png png = jpg.ToPng();
    
    await outStream.WriteAsync(new Res(){Png = png}); // !
}

async Task RequestNoFile(implicit IServerStreamWriter<Res> outStream) =>
    await outStream.WriteAsync(new Res(){SendFile = false}); // !
    
async Task<Jpg> RequestFile(
  implicit IAsyncStreamReader<Req> inStream,
  implicit IServerStreamWriter<Res> outStream,
  implicit ServerCallContext ctx) {
    await outStream.WriteAsync(new Res(){SendFile = true }); // !
    CheckCancellation(); // !
    Req msg = await inStream.ReadAsync(); // !
    CheckCancellation(); // !
    return msg.Png;
}

The code is a lot lighter and arguably cleaner than what it would look like if it passed around ctx, inStream and outStream explicitly every time. The code focuses on the main logic without bringing up the contextual dependencies, which are mentioned only in method headers. To show the impact, I marked all the places where the implicit application happens with a // ! comment.

Implicit parameters ease refactoring in some cases. Let us imagine that it turns out that RequestNoFile needs to check for cancellation, and therefore requires ServerCallContext to get access to the token:

async Task RequestNoFile(implicit IServerStreamWriter<Res> outStream, implicit ServerCallContext _) {
    await outStream.WriteAsync(new Res(){SendFile = false});
    CheckCancellation();
}

Because in the presented snippet RequestNoFile is called only from scopes with ServerCallContext provided, no other changes in the code are required. In contrast, without implicit parameters, every single call to RequestNoFile would have to be updated. Of course, if the calling context does not have that variable, it needs to get it anyway -- but if it does so implicitly as well, this benefit propagates further. This nicely reduces the complexity of adding new dependencies to routines.

Detailed design

General syntax

Since the implicit parameters appear similar to optional parameters, it feels natural to declare them in a similar manner:

void f(int x, implicit int y, implicit int z) {}

Regarding placement, it makes sense to mingle both kinds of special parameters together. Parameters could be also simultaneously implicit and optional as well:

void f(int x, implicit int y, implicit int z = 3, int w = 4) {}

Supplying implicit arguments from non-implicit methods

In order to avoid the mess known from Scala 2, there should always be a clear way of finding the values provided as implicit parameters. Therefore, I propose letting them be taken only:

• From the implicit parameters of the current method
• Through explicit application
• (OPTIONAL) from implicit local variables (and only local)

Hence this:

int f(int x, implicit int y);

int g() {
    return f(3, y: 42);
}

If supplying them manually starts getting annoying, then a possible workaround would be to lift the context with another method. So this:

void f1(implicit int x);
void f2(implicit int x);
void f3(implicit int x);

void g() {
    int arg = 123;
    f1(x: arg);
    f2(x: arg);
    f3(x: arg);
}

turns into this:

void f1(implicit int x);
void f2(implicit int x);
void f3(implicit int x);

void g() {
    int arg = 123;
    gf(x: arg)
}

void gf(implicit int arg) {
    f1();
    f2();
    f3();
}

Overloading

Resolution rules for overloading should be no different that those for optional parameters. When a method is picked based on the contex,t and there is no suitable implicit parameter in scope, it should result in an error.

Nested functions

In most common cases there should be no reason to prevent local functions from using implicit parameters of enclosing methods. Though, there are two exceptions where it would not work:

• When the nested function is static
• When the nested function shadows an implicit parameter by declaring another one of the same type

A workaround for the former is to declare the static function with the same implicit parameter. That also gives a reason to have a casual shadowing regarding the latter case.

Resolution of multiple implicit parameters

The design must consider ambiguities that emerge from use of multiple implicit parameters. Since they are not explicitly identified by the programmer, there must be a clear and deterministic way of telling what variables are supplied and in what order. A common way of tackling this is to enforce every implicit parameter have a distinct type and do the resolution based on that. It is a rare case that one would need multiple implicit parameters of the same type, and if so a wrapper class or a collection can be used (even a tuple).

There is a special case when inheritance is taken into account, as it can lead to ambiguities:

void f(implicit Animal a) {}

void g(implicit Dog d, implicit Cat c) {
    f();  // Which animal should be supplied?
}

This should result in an error, ideally poining to all variables that participate in the dilemma. However, as long as the resolution is deterministic, there should be no issue with that. A workaround in such situations is explicit application:

void f(implicit Animal a) {}

void g(implicit Dog d, implicit Cat c) {
    f(a: d);  // That's clear
}

If that feels doubtful, it could be a configurable warning that an implicit parameter is affected by subtyping.

Backwards compatibility

Since I propose reusing an existing keyword, all valid identifiers shall remain valid. The only added syntax is an optional sort of parameters, which does interfere with any current constructs, so no conflicts would arise from that either. There is also no new semantics associated with not using this feature. Thus, full backward compatibility.

Since there is a general convention to keep contextual parameters last anyway, transition of common libraries to use implicit parameters should be quite painless. That is because implicit parameters can still be used as positional ones, so the following codes shall run perfectly the same:

// Version 1.0 before implicit parameters
async void Send(Message message, CancellationToken token);

// LegacyEnterpriseSoftwareIncorporated's business logic
async void SendFromString(string s, CancellationToken token)
{
    Send(new Message(s), token);
}

and

// Version 1.1 after implicit parameters
async void Send(Message message, implicit CancellationToken token);

// LegacyEnterpriseSoftwareIncorporated's business logic
async void SendFromString(string s, CancellationToken token)
{
    Send(new Message(s), token);
}

...and of course

// Version 1.1 after implicit parameters
async void Send(Message message, implicit CancellationToken token);

// ModernStartupHardwareFreelance's business logic
async void SendFromString(string s, implicit CancellationToken token)
{
    Send(new Message(s));
}

Performance

These parameters turn into normal ones in an early phase of the compilation, thus no runtime overhead at all. Compilation time would be affected obviously, but it depends on the resolution algorithm. If kept simple (what I believe should an achievable goal), the impact should not be very noticeable. More than that, there is no overhead if the feature is not used.

Editor support

Since the feature would be desugared quite early, it should be easy to retrieve what arguments are applied implicitly. Thus, if some users find it confusing, I believe it would not be very hard to have a VS (Code) extension that would inform about the details of the implicit application. A similar thing to adding parameter names to method calls.

Drawbacks

Well, "implicit". This word is sometimes enough to bring doubts and protests. As much as I personally like moving stuff behind the scenes, I definitely see reasons to be careful. All that implicit magic is a double-edged sword -- on one hand it helps keeping the code tidy, but on the other can lead to nasty surprices and overall degraded readability.

One of the most common accusations against Scala is the so-called "implicit hell", which is caused by sometimes overused combination of extension classes (known there as, of course, "implicit" classes), implicit parameters and implicit conversions. I am not a very experienced Scala programmer, but I do remember finding Akka (a Scala library that uses implicits extensively) quite hard to learn because of that.

As mentioned before, there is an article by Scala itself, that points out flaws in the Scala 2 design. I encourage the curious reader for a lecture on how not to do it.

Also, there is a discussion under a non-successful proposal for adding this to Rust. The languages and their priorities are fairly different, but the critics there clearly have a point.

Alternatives

Resolution by name

Implicit parameters could be resolved by name instead of types. It allows implicit parameters to share type and solves all issues with inheritance, since types wouldn't play any role here. Although, it reduces flexibility since the parameters would be tied to the same name across all the flow of the code. This may slightly harden refactoring. A counterargument to that is that each implicit parameter should generally describe the same thing everywhere, so keeping the same name feels natural anyway and looks like a good pattern that might be worth enforcing.

Local implicit variables

To ease resolution and reduce the amount of code, some local variables could be declared as implicit as well. To avoid Scala 2 mess, it is important to allow this solely for method-local parameters and nothing more.

void f(implicit int x);

void g() {
    implicit int x = 123;
    f();
}

Unresolved questions

• Should we allow implicit parameters on properties?
• Should we allow implicit parameters on constructors?
• Do we want to allow declaring implicit local variables?
• Resolution by type vs by name.
• Should we allow passing an implicit parameter when it is of a subtype of the declared one? (assuming no ambiguities)?
• Should nested functions inherit implicit context from their declarators?

Design meetings

• https://github.com/dotnet/csharplang/blob/main/meetings/2022/LDM-2022-09-21.md#implicit-parameters

[HaloFour]

You have already opened an issue on this subject and it has been converted to a discussion per the rules of this repository: https://github.com/dotnet/csharplang/discussions/5989#discussioncomment-2516127

[radrow]

Yes, and I was asked to make it into an issue. Please check the last comment of the discussion you linked.

[HaloFour]

That you were, sorry, didn't notice the comment from Mads.

[alrz]

Linking to: https://github.com/dotnet/csharplang/discussions/3475

Something like that can be done using this feature but it doesn't save much as you would need to spell out each type in local function signature.

[svick]

One thing to consider regarding resolution by type: would it make sense to forbid implicit parameters of "primitive" types like int and string?

For a type with well-defined meaning like CancellationToken, there is very little space for mistakes or confusion: if a function has an implicit CancellationToken parameter, passing it to every called function that also has an implicit CancellationToken parameter is what you want.

But for a primitive type like int, implicit int by itself does not mean anything. So passing an implicit int parameter to a called function with an implicit int parameter has a high risk of doing the wrong thing.

[radrow]

I absolutely see your point @svick. Making primitive or "common use" types implicit is definitely a misuse of implicit parameters in most cases. Although, should we always forcefully prevent writing code that goes against our preferred patterns? Having an implicit int is not technically incorrect, it's just hard to imagine a case where it would be beneficial. More than that, with resolution by type the compiler would make it hard to abuse, since there could be maximum one implicit parameter of every such type.

If we want to consider some measures, here is a couple of ideas:

• Ban implicit parameters on value types (that solves int, but not string)
• Require some annotation/keyword on classes/structs that can be implicit (pollutes the code imo, requires libraries to adapt)
• Add warnings for builtin types that we think shouldn't be implicitly passed

My sense is that we won't prevent people from shooting themselves in the foot. What we can do is require such shots to be intentional -- which in my opinion is the case with implicit int.

---

Possible use of implicit int: education about the feature. Maybe someone wants just to play around and see how implicit parameters behave?

[svick]

Ban implicit parameters on value types (that solves int, but not string)

That wouldn't work, CancellationToken is a value type.

My sense is that we won't prevent people from shooting themselves in the foot. What we can do is require such shots to be intentional -- which in my opinion is the case with implicit int.

I don't think it's going to be clear that implicit int is somehow risky, when implicit CancellationToken is going to be the recommended practice. Especially when interacting with code from somebody else. E.g.:

void MyFunction(implicit int timeoutSeconds)
{
    MyOtherFunction();
    SomebodyElsesFunction();
}

void MyOtherFunction(implicit int timeoutSeconds);
// timeout is in milliseconds
void SomebodyElsesFunction(implicit int timeout);

And even more so when SomebodyElsesFunction didn't have an implicit parameter in previous version, so just upgrading it broke my code.

[CyrusNajmabadi]

Does scala do anything to prevent "implicit int"?

Perhaps we should require that implicits match not just on type, but also on parameter name? This would prevent improper matching of one implicit int to another unrelated one. However, it would mean if I had something like implicit bool performLogging, then that would work in an entire component for that pattern used everywhere.

Downside would be at component boundaries if the names did not match. E.g. some components using the name token while others use cancellationToken. But perhaps that's ok?

[HaloFour]

@svick

One thing to consider regarding resolution by type: would it make sense to forbid implicit parameters of "primitive" types like int and string?

Why? It may be considered abusive but it seems unnecessary to denylist an arbitrary set of types. A developer has to opt-in to using this feature anyway, if they want to use implicits that don't make sense (or at least don't make sense to us here) I don't think there's a reason to prevent them.

@CyrusNajmabadi

Does scala do anything to prevent "implicit int"?

No.

Perhaps we should require that implicits match not just on type, but also on parameter name?

Scala also doesn't do this.

However, it would mean if I had something like implicit bool performLogging, then that would work in an entire component for that pattern used everywhere.

IMO it would just make the feature that much more brittle than it already is. If someone wanted to pass around a bunch of implicit flags like that they could define a carrier struct and avoid the ambiguity.

[alrz]

It sounds like the only safe usage is about passing CancellationToken which is already solved with analyzers.

In any other case, why would you want to actually HIDE that something is passed as some kind of "context"?

(Right now the only implicit parameter is this and that's pretty fundamental to the language)

[orthoxerox]

I really like how this is handled in Koka. It's a bit more complicated than that, since effect handlers can define multiple values, functions and control statements, but if we restrict this to just values, then something like

Data FetchData(implicit CancellationToken token)
{
    ...
}

must either be called from a function that bubbles up that implicit (has as implicit CancellationToken token in its signature) or provides it explicitly:

with (var token = GetTheTokenFromSomewhere()) {
    var data = ValidateAndFetchData(request);
    //ValidateAndFetchData is implicitly passed the token and implicitly passes the token to FetchData()
    ProcessData(data); //Again, the same token is passed to ProcessData();
}

Of course, this is much more concise in Koka, where you can give a short name to your effects, so something like this could work:

implicit parameters CT
{
    CancellationToken token
}

Data FetchData()[CT]
{
    ... // token is in scope here
}

Data ValidateAndFetchData(Request request)[CT]
{
    ...
    return FetchData();
}

with (CT as { token = GetTheTokenFromSomewhere() }) {
    var data = ValidateAndFetchData(request);
    //ValidateAndFetchData is implicitly passed the token and implicitly passes the token to FetchData()
    ProcessData(data); //Again, the same token is passed to ProcessData();
}

[orthoxerox]

In any other case, why would you want to actually HIDE that something is passed as some kind of "context"?

@alrz it's more or less in the same boat with dynamic scoping or associated types. Explicit context passing is good, but noisy.

[alrz]

I'd agree that it's noisy but I'm concerned on how this works out in practice. Looking at some places that may use this feature:

https://github.com/dotnet/roslyn/blob/8a31e4d004314c170cb4f85ec946a7e40deef46c/src/Compilers/CSharp/Portable/Binder/Binder_Patterns.cs#L162-L165

All these are candidates for an implicit parameter, but you will need to depend on IDE to find usages in case any kind of change is required. Immediate compiler feedback helps but since its completely hidden at the call-site, it's prone to abuse and can result in surprises whether you're writing or reading code with implicit parameters all over the place.

[alrz]

If only implicit parameters were allowed to be passed implicitly, I think it could mitigate the surprise factor.

void M0(implicit object o) => Use(o);

void M1(implicit object o) => M0(); // ok
void M2(object o) => M0(); // error

[radrow]

If only implicit parameters were allowed to be passed implicitly

This is a key constraint of the design. You still need to explicitly indicate that some stuff is handled implicitly.

[sab39]

One use case for this feature that I would expect to make heavy usage of is the ability to write DI-friendly extension methods.

Until recently I worked on a codebase that relied heavily on ambient context, where I'd commonly use extension methods to facilitate more readable code. For example, foo.Frob().Wrangle() is often much clearer than Frob(Wrangle(foo)), and without extension methods foo?.Frob()?.Wrangle() needs multiple lines or a mess of ternary operators.

The project I work on now uses DI rather than ambient context, which is obviously more in line with modern best practice, but without an ambient context, injected dependencies need to be passed to the extension methods explicitly, which undermines the readability that's the goal of such extension methods in the first place.

With implicit parameters, this would no longer be an issue - as long as you could apply implicit to properties and fields rather than just parameters (and locals):

public interface IPrioritizer
{
  int GetPriority(Operation op);
}
public static class PrioritizationExtensions
{
  public static IEnumerable<Operation> Prioritize(this IEnumerable<Operation> operations, implicit IPrioritizer prioritizer)
    => operations.OrderBy(op => prioritizer.GetPriority(op));
}
public class PrioritizedDispatchService
{
  protected implicit IPrioritizer Prioritizer { get; }
  public DispatchService(IPrioritizer prioritizer)
  {
     this.Prioritizer = prioritizer;
  }
  public void DispatchOperations(IEnumerable<Operation> operations)
  {
    foreach (var op in operations.Prioritize()) // passes this.Prioritizer because of the implicit modifier on the Prioritizer property
    {
      op.Dispatch();
    }
  }
}

One important open question with this approach is whether, for example, Prioritizer would still be considered implicit in a subclass of PrioritizedDispatchService. For my own use cases, it'd be much more convenient if the implicitness were inherited, because one of the main reasons for having a common base class in the first place is to avoid the need for duplicated code when inheriting from it. But I can see a persuasive counterargument that it's confusing and dangerous if the meaning of code can be 'invisibly' changed by the base class without some kind of explicit opt-in.

[iam3yal]

@sab39 I don't know how I feel about implicit properties and fields, personally I think that only implicit parameters should be supported but if the LDT are going to decide to extend it to more than just that then it should be limited to the current class, meaning private otherwise it will reduce code readability greatly especially when combined with inheritance.

[MgSam]

While typing less is nice and marginally beneficial- code is read far more times than it is written. And there is no doubt that this makes the code more confusing and harder to read. Now, instead of reading a line of code and knowing exactly what is being called, I need to actually rely on an IDE to either F12 to whatever method is actually being resolved or scroll up and check, double check, and triple check what implicit parameters might be in scope.

Code like this would quickly become a nightmare to read when pared with method overloads.

[fifty-six]

Requiring explicit specification of variables that can/will be used implicitly also somewhat matches things like State in Haskell, where you don't have to pass around a context, but it's pretty explicitly specified so you know where it's coming from. I've found that when using it, it's very convenient and it's still clear when the context is being used. Though, a difference in that language is that as it's done with Monad, you can see a/the context is used because you have to very explicitly bind or use do, though I don't know how you'd fit that kind of thing into C#. That's also helped by the lack of void returns, so when you see something used at top level without any binding in a do block you'll know it's using the 'context'.

[Richiban]

I don't like the idea of using parameter names as part of the matching algorithm, because IMO it gives parameter names an unwelcome, far-reaching significance. For example, if I have an implicit parameter that I want to rename I have to contend with the fact that parameters will now get renamed all the way up the call stack.

Similarly, I may be blocked from actually using this feature if I want to call methods in two libraries I don't control that haven't given the same name to the parameter:

// Library A
public void F(implicit CancellationToken cancellationToken) {...}

// Library B
public void G(implicit CancellationToken ct) {...}

// My library
public void M(implicit CancellationToken ???) // What name do I give this parameter?
{
    A.F();
    B.G();
}

When talking inspiration from other languages, we should also mention Kotlin's prototype Context Receivers feature. In it, they recommend that context parameters (their terminology for implicit parameters) are of a type that was explicitly designed to be used as such. You're not required to implement a specific interface or anything like that, but it's expected that your implicit parameter would be a type such as CancellationTokenProvider or CancellationContext rather than the CancellationToken itself.

While I agree with the sentiment behind this, I think in C# there are good reasons for wanting this to be as compatible as possible with the various existing method signatures out there in the wild. Still, Kotlin is a language that is well worth keeping an eye on for new language features.

[radrow]

@Richiban You have a very good point. I think it would be a nice linter rule to enforce certain name convention for implicit-param types, such as what we have for attributes and streams.

[Leemyy]

I can definitely think of times where I would have loved this as a feature.

There is one potentiall pitfall that came to mind, though. If you start out with code similar to the following:

void e(CancellationToken token);

void f(CancellationToken token);
void f();

void g(CancellationToken token) {
    e(token);
    f();
}

and then upgrade by adding implicit, you could suddenly end up binding to a different overload:

void e(implicit CancellationToken token);

void f(implicit CancellationToken token);
void f();

void g(implicit CancellationToken token) {
    e();
    f(); //now binding to a different overload of f
}

The way I see it, this could be addressed in several ways:

1. If an ambiguity exists between an overload with an implicit parameter and an overload without, pick the one without the implicit parameter.
2. Warn on a function definition, if it only differs from another overload by implicit parameters.
3. Warn on any call site that is ambiguous between overloads that only differ by implicit parameters.

[HaloFour]

@Leemyy

This situation already exists with optional parameters (on which this implicit parameter proposal is based), and the compiler will already prefer the overload without the optional parameter:

SharpLab

using System;

class C {
    static void M() => Console.WriteLine("Without optional");
    static void M(string foo = null) => Console.WriteLine("With optional");
    
    static void Main() {
        M(); // prints Without optional
    }
}

[Eli-Black-Work]

It looks like this has a proposal champion but also has 3x more downvotes than upvotes. Does having a proposal champion mean that this feature is slated for implementation?

[CyrusNajmabadi]

Does having a proposal champion mean that this feature is slated for implementation?

No. It means there is an LDM member willing to carry it through the design process. This is merely at the proposal stage currently.

[333fred]

And of note, the most recent time this was brought up in LDM, that negative community sentiment was mentioned.

[Eli-Black-Work]

Got it, thanks! 🙂

[Richiban]

I thought I'd talk about a really cool use case for this: in Kotlin "contexts" can also be defined for operators. A domain I'm working in a lot right now is VS Code extensions (I know it's Typescript but the situation would be the same for a C# codebase). It involves a lot with Positions, which is basically a "point" in a text document sense i.e. a line and character number. We should be able to transpose a Position by adding two positions together, such as:

Position p1 = ...
Position p2 = ...

Position result = p1 + p2;

but the problem is that you could easily create a point that isn't valid; such as it's off the end of the given line or the line number is greater than the number of lines in the document. In order to properly add two Positions together you need access to the Document as well, but how will you pass it in? You can't use + any more since it's a binary operator. You can fall back to a method such as p1.Add(p2, document) but that feels like a design smell and it's a shame that we've lost the simple operator form. You could leave the "normalisation" of the point to the Document type, like this:

Position result = p1 + p2;
result = document.Normalise(result);

but it's easy to forget to do this (thus creating a pit of failure). In Kotlin, you can solve this by placing a context receiver on an operator function:

context(DocumentContext)
operator fun Position.plus(other: Position): Position {
    ...
}

and now, our domain is nicely designed in such a way that you are able to add two Positions together in the context of a document:

context(DocumentContext)
fun DoTheThing() {        
    Position p1 = ...
    Position p2 = ...

    Position result = p1 + p2; // Now it is guaranteed that `result` is adjusted to fit within the document
}

This is something that would be very valuable in C# too; I can imagine it working like this:

// Definition
public static Position operator +(Position a, Position b, implicit Document document) 
{
    ...
}

// Use
public void DoTheThing(implicit Document document)
{
    Position p1 = ...
    Position p2 = ...
    
    var result = p1 + p2;
}

So, operators would be allowed to have more than the regular number of parameters but any additional parameters must be implicit.

[CyrusNajmabadi]

That example is highly worrying to me. It genuinely makes me feel like a free being used to mask bugs. I.e. of them program is trying to manipulate points like this such that it goes out of bounds, then it has done something wrong. And implicitly trying to make that but happen is just hiding a deeper issue.

This is not idle concern for me either. Many many times I've seen in the development of VS components making such mistakes. Generally because they were mixing data inappropriately (like points from one time and snapshots from another; or points from two different times). Having a system implicitly papering over that would lead to masking that instead of failing early and obviously, forcing the underlying problem to be fixed.

[CyrusNajmabadi]

document.Normalise(result);

So we have code in roslyn that does this. But only very rarely, and only with comments explaining why it's the right thing to do. For example, there are times when we may be searching a stale index, whose positions then might not be in the bounds of a file that has since changed. In such a case, we do need to normalize things, but we document that that is both intentional and represents the fact that the feature itself is trying to be "best effort" and this will likely take the user to the right location most of the time, and that we will tell the user that the results are potentially stale, making this an acceptable experience.