Top-level members

[jjonescz]

Proposal: https://github.com/dotnet/csharplang/blob/main/proposals/top-level-members.md
Champion issue: #9803

[julealgon]

I'm still surprised it took so long to get to this considering all the work done for Program.cs.

Will definitely help with language adoption and may be useful in some enterprise contexts too.

[Richiban]

This is a loooong-requested feature, and I am surprised (but very happy!) to see it being considered since I was sure the discussion was closed as "Likely never" the last time

[Richiban]

Copying in the link to the markdown document: https://github.com/jjonescz/csharplang/blob/tlm/proposals/top-level-members.md

[jjonescz]

Thanks, added to the OP

[Richiban]

I think this is a great idea, but I have a few concerns with the proposal:

I don't think fields (or auto properties) are a good idea (certainly not for the first release; once out in the wild maybe my concerns will be assuaged). Global mutable state that floats around outside of a class is bad juju, in my opinion; it's fine for methods (which will become 'functions') but allowing state will just encourage people to start using files as file-scoped classes.

Regarding mixing type declarations and top-level members in the same file: it feels like this should be allowed but there's a question about how it gets lowered; namely are the declared types nested inside the implicit type? I'd say they shouldn't be, otherwise adding a member to a file would cause the declared types to "move", perhaps disappear entirely (if their visibility is left to the default).

[julealgon]

Global mutable state that floats around outside of a class is bad juju, in my opinion;

I understand your concern, but this shouldn't be up to the language to "protect" the user. I think the functionality being orthogonal is more important than making these "best practice decisions" at the language level.

Besides, global state for something that is simple enough is totally fine. By enforcing "enterprise patterns" on the language it just makes it less flexible and less intuitive overall.

[KennethHoff]

Shared mutable state is the source of a huge number of errors; especially with parallelization in the picture. I don't believe that justifies artificially limiting the feature however

[MgSam]

I understand your concern, but this shouldn't be up to the language to "protect" the user.

Actually it is up to the language and this was always a big part of C#’s design philosophy (as opposed to something like C++). The “pit of success”- https://blog.codinghorror.com/falling-into-the-pit-of-success/

[mungojam]

If it was just static methods / extensions exposed, then it isn't mutable state and would bring many of the benefits

[mattwar]

How does this exist differently than the existing top-level members that are considered locals to an implicit constructor of the Program class?

[jjonescz]

Currently a top-level void M() { } or int x = 123; already means something, and this proposal seems to change that meaning.

The new meaning only applies if you put them in a namespace (which is currently not possible), so existing code wouldn't change.

[HaloFour]

I see. That makes sense. Thanks!

[RikkiGibson]

I think this difference has been nagging at my brain a little bit. The top-level of a file is a global namespace. So it just feels weird for it to not be able to do certain things that the explicit namespace can do with this feature. I'm not sure yet whether I consider that a real problem or not.

[HaloFour]

I can see an argument that folks would want to use this feature without needing namespaces, too.

[jjonescz]

I can see an argument that folks would want to use this feature without needing namespaces, too.

I guess we could allow that. The presence/absence of non-function top-level statements would determine whether it's top-level-statements Main, or the new top-level members. The only "breaking change" scenario would be if you had only local functions as top-level statements (but that's not a useful thing to have today).

EDIT: Actually there would be a problem of how to bring them to scope (there is already a bullet point under Alternatives for that).

[Richiban]

I'm copying a comment I made on the PR because perhaps that wasn't the best place to put it:

(With respect to what happens if you mix top-level members and types in the same file).

My mental model of how this should work goes like this:

Rather than thinking "If this file contains top-level members then lift the contents of the file into a generated class" I think "For each declaration in this file, if it's a member, then lift it into a generated class".

So

namespace N;

void M1() {}

class C1 {}

void M2() {}

class C2 {}

void M3() {}

becomes

namespace N;

partial static class TopLevel
{
    void M1() {}
}

class C1 {}

partial static class TopLevel
{
    void M2() {}
}

class C2 {}

partial static class TopLevel
{
    void M3() {}
}

rather than

namespace N;

static class TopLevel
{
    void M1() {}

    class C1 {}
    
    void M2() {}
    
    class C2 {}
    
    void M3() {}
}

[colejohnson66]

I confused about this proposal. Sure, C++ and Rust support them, but the LDT’s consistent argument to this feature through the years is “using static exists. Use it.” Why now?

I’m not against it. Just wondering “what changed?”

[Richiban]

I think there's been a movement in the last few years in the LDT that they should cater more to the features that users expect to exist, coming from other languages.

C# and Java are kind of alone in the fact that they don't let you simply declare a method on its own and then call it from elsewhere in your program; they make you wrap it in another construct (a static class) first. You must always reference the function with its class name as C.Foo() unless you use a special kind of import (using static N.C).

Although this is the way it's always been for C#, you've got to admit it is weird (and decidedly not beginner-friendly). Coming from OOP principles I'm not sure I think that static class even really makes sense as a concept; they were introduced as a kind of workaround for the fact that C# doesn't allow free methods or have the concept of modules.

So, I support this proposal, although whether or not it's worth the dev time is a decision for the design team.

[ufcpp]

Just wondering “what changed?”

I guess file-based programs are a very significant factor.

[jjonescz]

using static exists. Use it

Sounds analogous to "Program { static void Main() { } } exists - use it," yet we added top-level statements. Many language features are about removing boilerplate.

[TahirAhmadov]

Yes, I definitely think beginner friendliness is a good idea. Doesn't really hurt the "professionals", and makes the language easier to get into.

[RikkiGibson]

To me, extensions are what has moved the needle here. I think at minimum we should do something to allow an extension to be declared in a namespace. The other member kinds I am more ambivalent about at this moment.

[En3Tho]

Are there examples of code that would benefit from this so much? I fail to see how this is better than "global using static ...".

I think if user specifically wants members of some static class to be discoverable in ecope of namespace then a simple attribute similar to F#'s AutoOpen would suffice.

[Richiban]

This is all about making C# more beginner-friendly and making the language work in way that those familiar with other languages expect. It's also closing the gap between top-level statements in the program entry file and the rest of your program.

As an aside I support this feature on that second point alone; C# has long had a bit of a problem with features that "fall off a cliff", where you've written code with one form but now you need to do something but the languages says "Sorry, you're going to have to use a different form if you want to do that". So they're addressing the auto property case with the field keyword and now they're proposing tackling the top-level statements case with this (where you can start writing a C# program with top-level statements but, as the point you want to split your Program.cs file up because its grown you now have to use different language constructs in order to do that).

[jjonescz]

"global using static ..."

You seem to be focusing on the consumption side. That indeed doesn't change much (you still need a using) and hence that's not the motivation for this feature. The motivation is the declaration side. For example, consider extension members - you won't need to declare them in (otherwise useless) wrapper static class anymore.

[UniqeId6542]

If the main point is to make C# more beginner-friendly, then the idea is to reduce code overhead?
So, class-statements could accomplish the same thing - with potentially less confusion?
Currently, C# supports file-scoped namespaces:
namespace MyNamespace;
So, the same could be done for classes:
class MyClass;
Or, combine the two:
class MyNamespace.MyClass;
Since it seems like the namespace line will still be required with this proposal, then declaring the class the same way doesn't change the overhead. But class-statements also don't change the idea that methods are part of classes nor requires a compiler generated class to be made.

[ikkentim]

class MyClass; is already legal code with meaning today. We can't change that.

Maybe that doesn't matter? (correct me if I'm wrong)

Today class MyClass; void Foo(){} is illegal. Top level class MyClass; <no members> and the class MyClass; of today would result in the same. Only thing is that class Class1; class Class2; is legal today, and it wouldn't be if both were top level class statements. But that could be solved by using "current" classes when multiple class MyClass; exist in one file.

[CyrusNajmabadi]

Maybe that doesn't matter? (correct me if I'm wrong)

You're correct in that we could choose to make that illegal code have this meaning. The question is "should we?" esp if there are alteranate meanings we'd like it to have.

for example, this would now eliminate the possibility of having types and top-level members intermix in this fashion. Which is something i would like us to be able to do.

[colejohnson66]

IMHO, the desire to write...

class MyClass;

<members>

...is misguided. None of the mainstream languages allow that. Not Java. Not Rust. Not Python. Not PHP (yes, it's still mainstream). Not JavaScript. Yes, C++ might if you consider the implementation of a class (the .c[pp|xx] part), but the definition itself (the .h[|pp|xx] part) still requires braces.

Yes, it would be just a follow-up from file-scoped namespaces, but the amount of times I've seen...

namespace A
{
    <members>
}

namespace B
{
    <members>
}

...is extremely small - usually only done by source generators. On the other hand, the number of times I've seen...

class MyClass
{
    <members>
}

interface IFace
{
    <members>
}

enum MyEnum
{
    <members>
}

...(or some variation), is very high. Especially if one does the "non generic and generic interface" pattern:

interface IFace
{
    <members>
}

interface IFace<T> : IFace
{
    <members>
}

Yes, you (the reader) might not do that (multiple types in one file), but it's a hell of a lot more common than multiple namespaces in one file.

[OJacot-Descombes]

This would not exclude having more than one type declaration per file.

class MyClass;
<members>

class MyClass.NestedClass;
<members>

class AnotherTopLevelClass;
<members>

The same approach could be used for namespaces. This would extend the existing file-scoped namespaces feature.

[CyrusNajmabadi]

We considered that and explicitly rejected because there was a split on what that would mean (many believe it should be a nested type, many believe it should be a sibling.

[sator-imaging]

what's happening on conflict? or force limit to internal/file visibility? (I expect limiting)

// in some assembly
public void Log(string msg) => ...;

// in my code
void Log(string msg) => ...;

Log("which one");

[jjonescz]

Same as what would happen with the equivalent lowered code. Assuming the default accessibility is internal:

// in some assembly
class TopLevel
{
    public void Log(string msg) => ...;
}

// in my code
class TopLevel
{
    internal void Log(string msg) => ...;
}

TopLevel.Log("which one"); // ambiguity error

[MgSam]

Implicitly static global variables are an awful idea and will lead to countless bugs. I totally disagree with the comments saying this makes the language more approachable. C, C++, Java, C# have been top ten languages for decades. Countless millions have learned to write them.

Also let’s not fall into the fallacy of thinking adding features reduces complexity. Adding features always increases complexity because more there are more permutations of ways of writing the code you must understand.

[jjonescz]

This feature doesn't really introduce anything new, it's just a syntactic sugar for stuff you can write today. Specifically, you are talking about static mutable fields - this feature just makes it possible to use them as MyField instead of MyClass.MyField. That's it.

[En3Tho]

Yes but the is an important difference: to have all this you have to deliberately OPT-IN via using static. Now you will have to opt-out instead? How do you even opt-out?

[jjonescz]

You still need using for the namespace that the top-level members are declared in. Similar to extension methods (those are also brought in just by importing a namespace, no need to reference the static class directly). So the opt out is either not using that member (not sure why would you need to opt out any more than that) or not having using Namespace for it.

[CyrusNajmabadi]

How do you even opt-out?

Similar to all imports, you would not pull in that using. It's the same as anyone adding extension methods (or any symbols for that matter) to a namespace. It's now just not limited to just extensions.

[OJacot-Descombes]

Constants
The proposal does not mention constants. They should be allowed too.

Disambiguation
My proposal (call site): Namespace.TopLevelMember(); without the intermediate (unspeakable) class name. This would disambiguate between top-level-members of different namespaces as well as between top-level-members and class/struct members.

[jjonescz]

The proposal does not mention constants. They should be allowed too.

Thanks, I'll add them.

My proposal (call site): Namespace.TopLevelMember(); without the intermediate (unspeakable) class name. This would disambiguate between top-level-members of different namespaces as well as between top-level-members and class/struct members.

That should already be the currently proposed state.