How do we avoid falling into line by line translation from GDScript to C#?

[paulloz]

Hey 🙂

I was reading through the recent updates in the documentation and stumbled on a C# example that IMHO warrants a bit of discussion. I noticed it due to the recent PR on the CharacterBody2D page (#6614), but the part that bugs me was already there in the 3.x documentation.

So, on this page, we find the following snippet of code.

public override void _PhysicsProcess(double delta)
{
    var collision = MoveAndCollide(Velocity * (float)delta);
    if (collision != null)
    {
        Velocity = Velocity.Bounce(collision.GetNormal());
        if (collision.GetCollider().HasMethod("Hit"))
        {
            collision.GetCollider().Call("Hit");
        }
    }
}

It is (as almost always) a direct translation of the GDScript example. More often than not, converting examples this way is fine. However, here, we are taking a very "duck typing-y" approach of what was returned by collision.GetCollider()... And I'd argue presenting this as a good approach in C# could be harmful (I lack a better word here) to the reader. In this particular instance, I guess most people would write this using an interface. But we don't really elaborate on what the object containing that Hit() method would be on this page, so I don't know if there's a point.

Anyway, I'm of course not saying we need to tailor every single C# code block completely differently than their GDScript counterpart. But I was curious of other people's opinion about this, if we should try to "correct" this kind of thing when we see them or if I'm just entirely delusional.

Edit: this was tagged automatically by GH, but it should probably be "discussion" instead of "enhancement"?

[raulsntos]

The problem is that in a tutorial/manual, while you are able to provide code in multiple languages, the text stays the same and that makes it challenging if you need to describe completely different approaches depending on the language.

There are plenty of examples of this in the documentation, see the Saving Games page, which uses duck typing and Godot's JSON serializer while it may better to use interfaces and one of .NET's more powerful serializers.

I've been thinking about adding notes throughout the documentation that mention related .NET APIs that users may want to consider so that, at the very least, they are aware that there are more options out there. Little notes in the documentation will hopefully not be too in your face for non-C# users, while still providing additional information for C# users. I don't know if this would be very helpful though.

Another idea, that I think is somewhat related to this and #6596 is to have a separate documentation website for C# so that we could write tutorials/manuals that use C# features and not worry that it's language-agnostic. However, because our resources are limited given that most of us do this on our free time, I think the website would get outdated pretty fast.

I'm pretty sure the C# documentation will improve over time, and will love to hear any ideas to this end!

But I was curious of other people's opinion about this, if we should try to "correct" this kind of thing

Specifically about this last point, I think there are a lot of possible improvements that could be made to the current documentation without going overboard and I'd be OK merging them, but I'd like to make sure our documentation is more consistent overall, currently we don't even respect our style guide in a lot of examples.

[paulloz]

The problem is that in a tutorial/manual, while you are able to provide code in multiple languages, the text stays the same and that makes it challenging if you need to describe completely different approaches depending on the language.

Absolutely, that's why I was saying that I'm not expecting the examples to all always be different in both languages. But I think we do have a bit of wiggle room to stay true to the surrounding text while being idiomatic. For instance, if we continue with the same page, the surrounding text here only says "If the colliding object has a hit method, we also call it". I'd argue that the following stays true to that text while being "better" C# code.

if (collision.GetCollider() is IHittable hittable)
{
    hittable.Hit();
}

Another idea, that I think is somewhat related to this and #6596 is to have a separate documentation website for C#

I don't think this actually what we'd want, I agree. It would not be maintainable. For me, the scope of #6596 is the class reference only.

I'd like to make sure our documentation is more consistent overall, currently we don't even respect our style guide in a lot of examples.

One hundred percent. When I edit a page, I try to bring all the C# code blocks up to standard. It's slow, but I agree with you that the quality of the C# documentation improves little by little. I'm always happy to help review PRs if it can help to take a bit of weight off your shoulders.

[raulsntos]

For instance, if we continue with the same page, the surrounding text here only says "If the colliding object has a hit method, we also call it". I'd argue that the following stays true to that text while being "better" C# code.

if (collision.GetCollider() is IHittable hittable)
{
    hittable.Hit();
}

I agree that the example still fits the text well enough, though I'm worried that users may be confused as to where IHittable is coming from, since it's not a type provided by Godot or the BCL, we'll likely want to add some text explaining what it is and then that may be confusing to GDScript users.

Another idea, that I think is somewhat related to this and #6596 is to have a separate documentation website for C#

I don't think this actually what we'd want, I agree. It would not be maintainable. For me, the scope of #6596 is the class reference only.

That's how I see it too. I wouldn't mind a dedicated C# class reference, and if we were to have a separate website for that, it's only natural that users would expect tutorials/manuals in that website too which is why I mentioned it. However, I think we can get away with just cross-linking the two websites.

One hundred percent. When I edit a page, I try to bring all the C# code blocks up to standard. It's slow, but I agree with you that the quality of the C# documentation improves little by little. I'm always happy to help review PRs if it can help to take a bit of weight off your shoulders.

I'd love to dedicate more time to documentation, but as you might imagine due to the 4.0 release I've been postponing it since other work took precedence. The PRs you've opened have been fantastic, I really appreciate it. Feel free to review PRs too.

[smolten]

As someone who loves compile-time errors, I would like to see SOME impetus for Godot C# docs to point users towards better practices in C#.
And, I recognize that C# scripts ought to remain 99% identical to GDscript docs.

So, how about Tooltips inserted on GDScript functions in C# docs. To show up on mousing over the function name:
if (collision.GetCollider().HasMethod("Hit"))
{
collision.GetCollider().Call("Hit");
}

• GDScript HasMethod("MethodName") can be removed. C# Compiler will fail if MethodName does not exist.
• GDScript Call("MethodName") can be replaced with C# MethodName()

I have just started trying Godot so I am unaware of the performance cost of dynamic vs compiled calls.
But maintaining strings that are not checked by the Compiler is certainly a drain on programmer time spent fixing errors.
Obviously - anybody writing hot loops in Godot should translate them to C# and not use GDScript dynamic calls - Obviously! But what if GDScript users had plenty of examples of proper C# behaviour [ ;) ] from the outset?