Search Unity

Concerning direction of C# naming convention in Unity

Discussion in '2018.2 Beta' started by Peter77, Jun 3, 2018.

  1. Peter77

    Peter77

    Joined:
    Jun 12, 2013
    Posts:
    4,120
    In my opinion it's not important what C# naming convention you use, but it's important to be consistent. Consistent in the sense that you use one naming convention for the entire API.

    Right now, I found three different naming conventions in Unitys API:
    1. The old naming convention everybody knows by now
    2. .NET standard conventions, see here
    3. "Shader programming like everything in lower case" convention, see here
    I would very much prefer if you can stick to one naming convention only.

    I understand if you want to transition to another naming convention. It means we have to deal with two different naming conventions for a couple of years. Not ideal, but I understand the idea behind it.

    What I don't understand is, and believe you don't do yourself a favor by doing that, to add more than two different naming conventions. It's going to make the transition for you even harder.

    I also do understand your intention with the new math library to make it easier for shader programmers to write C# math code. But overall, you write C# math code and it should feel like a first class citizen in C# land.
     
    Ziflin, rizu and dadude123 like this.
  2. dadude123

    dadude123

    Joined:
    Feb 26, 2014
    Posts:
    787
    Indeed, every language has its own conventions and mixing them to make things "easier" sounds cool at first, but in the end it's C# and *not* GLSL or Cg or anything else.

    You could have simply made a wrapper that people can use with
    using static GLSLSyntax;
     
    laurentlavigne and Peter77 like this.
  3. hippocoder

    hippocoder

    Digital Ape Moderator

    Joined:
    Apr 11, 2010
    Posts:
    25,618
    ECS is worth keeping how it is, especially if the plan is to generate shader code and vice versa someday. That can be a special case, so long as everything else remains consistent. In many systems, forcing consistency causes more problems than it can solve, just a thought.

    So as long as this behaviour is the exception rather than the rule I'm cool with it.
     
    recursive and dadude123 like this.
  4. dadude123

    dadude123

    Joined:
    Feb 26, 2014
    Posts:
    787
    You are actually completely right. I have had situations just like that in the past, looking back i think some more leeway would have been a much better choice.

    Personally I'd prefer making use of 'using static' whenever possible tho to satisfy both sides :)
     
    hippocoder likes this.
  5. Gru

    Gru

    Joined:
    Dec 23, 2012
    Posts:
    138
    I agree this is important.
    It is mostly understandable they want to migrate to a .NET Standard naming convention, even if it's a bit annoying. However, the inclusion of "shader programming convention" is totally off putting. So, if I made a library for C# that is inspired by a library from another language, I should change the naming convention just for that library?! The logic simply doesn't hold water. Also, "making it easier for shader programmers" is a totally ridiculous idea. Please consider changing this while the proliferation of this code is minimal.
     
    interpol_kun and dadude123 like this.
  6. rizu

    rizu

    Joined:
    Oct 8, 2013
    Posts:
    1,177
    I feel the same way, it's weird to not go with .NET naming standards on math library while other Unity libs transition to it. To me, it feels like the decision over this was made by few people internally because they simply preferred the naming convention themselves. It's not uncommon in this industry to let few specialists have their own way to keep them happy. For example other(tm) game engine I've used let their physics programmers use conventions not allowed in the rest of the engine code.

    All in all, if you pick a naming convention, stick to it. It's like 101 thing on all software development. I have no idea why Unity doesn't want to do this.
     
  7. rizu

    rizu

    Joined:
    Oct 8, 2013
    Posts:
    1,177
    I'd really emphasize the word IF here. If this is the reason for this decision, they should be transparent about it and explain the reasoning.

    The explanation I've seen so far is "it's easier to port code from shaders this way" and that is not much of a reason at all, considering how tiny the math lib is and how they need to handcraft every function to play nicely with Burst anyway.
     
    interpol_kun likes this.
  8. hippocoder

    hippocoder

    Digital Ape Moderator

    Joined:
    Apr 11, 2010
    Posts:
    25,618
    I don't think it's a problem. Consistency taken too far is actually a bigger problem especially if it causes more code you have to maintain.

    In this case I'm not seeing the problem. It's a math lib. It's really straight forward.
     
  9. rizu

    rizu

    Joined:
    Oct 8, 2013
    Posts:
    1,177
    Issue isn't if it's easy to use or only on some specific library. If we allow exceptions for every "special" system out there, there's no convention at all. It's bad enough that we have two different naming conventions already, mixing third one there isn't doing any favors to new people trying to understand all this, it's just against all common sense.

    I'm not personally upset that Unity does this for the new math lib, it doesn't change way I work in any way. I just wanted to offer my opinion and give support for people who are worried about this as it does fragment the way you use the engine and does it for reasons that are difficult to understand (if there's a hidden agenda behind it, I'd love to hear about it).
     
  10. Laicasaane

    Laicasaane

    Joined:
    Apr 15, 2015
    Posts:
    31
    I only feel bad about the old convention that was made to fit both C# and UnityScript. I wish they hadn't made that choice in the first place.
     
  11. Prodigga

    Prodigga

    Joined:
    Apr 13, 2011
    Posts:
    779
    Unity wouldn't be forcing consistency on anyone. The point is, the foundation code should at least follow proper .Net standards throughout (Unity libraries), leaving the user with the choice of following the .Net standards throughout their code, or just ignoring it and doing whatever they want (because it's their own project).

    But now, there is no choice. Your code is going to have to be a mix bag of standards because Unity decide they wanted to do that. You can't have consistency if you want to have consistency.

    It's almost like they should've just followed the .Net naming standards from the start, they could have avoided wasting all this time fixing their naming standards. I'm sure they won't make a mistake like this again in the future, right? ^_^
     
    Peter77 likes this.
  12. TJHeuvel-net

    TJHeuvel-net

    Joined:
    Jul 31, 2012
    Posts:
    413
    And why are there special systems at all? How is a special system in line with performance by default, i think by making it a special system you are making it more difficult to use. A higher barrier for entry, maybe some people would not use this new math library because its a special system, and would stick to the old one instead.
     
    dadude123 and hippocoder like this.
  13. hippocoder

    hippocoder

    Digital Ape Moderator

    Joined:
    Apr 11, 2010
    Posts:
    25,618
    Upon reflection I concede it would be better to have the syntax cased like Mathf because C# is the most frequent use of Unity mathematics. Parity with shaders would be the minimal use case and something Unity can probably fix their side...
     
    laurentlavigne and Peter77 like this.
  14. dadude123

    dadude123

    Joined:
    Feb 26, 2014
    Posts:
    787
    Will Mathf be marked with the [Obsolete] attribute when the math library gets integrated?

    At least then people would know what to use. If they use those methods in a context where there's no burst compiler or anything, then the methods still work as intended. And when used in ECS then all the better.

    I mean why have two static classes with math classes at all.
     
  15. JonHUnity

    JonHUnity

    Unity Technologies

    Joined:
    Sep 16, 2016
    Posts:
    5
    Hi everyone. I'm the tech lead on the recently formed Code Fitness team at Unity, which among other things curates and enforces our internal coding standards. As we maintain a large existing codebase and iterate on the workflow tooling around conventions, it's not unreasonable to conclude that our standards are unsettled, but that is not quite the case.

    Recently we adopted Microsoft's Framework Design Guidelines as our base set of conventions around public API with one significant exception around naming to limit inconsistencies in our codebase. The exception is this:

    As we implement more engine features in pure ECS, these new features will all adopt Microsoft's PascalCase naming scheme for properties.

    As for the Unity.Mathematics package, it is currently released as a preview, and the public API is still subject to change. There may be an opportunity to deviate from the guidelines for this specific package.

    Hope that clears things up.

    Edit: Clarified the state of the API on the Unity.Mathematics package.
     
    Last edited: Jun 18, 2018
  16. dadude123

    dadude123

    Joined:
    Feb 26, 2014
    Posts:
    787
    Thank god! Happy to hear that!
     
  17. Ethan_VisualVocal

    Ethan_VisualVocal

    Joined:
    Mar 23, 2016
    Posts:
    144
    On this topic, does anyone have feedback for what kinds of Unity-specific fields might need special naming rules, e.g. [SerializableFields] ? The devs for the Rider C# IDE + Unity plugin are wanting feedback but I'm struggling to help:

    https://youtrack.jetbrains.com/oauth?state=/issue/RIDER-8339 (Scroll to bottom for last comment by Matt Ellis)

    These guys are super responsive, so any guidance here would end up benefiting lots of Unity devs.
     
  18. JonHUnity

    JonHUnity

    Unity Technologies

    Joined:
    Sep 16, 2016
    Posts:
    5
    Ethan_VisualVocal likes this.
  19. TJHeuvel-net

    TJHeuvel-net

    Joined:
    Jul 31, 2012
    Posts:
    413
    Super glad to hear that, and that this team exists! There is a lot of feedback in this thread too.
    Thanks so much!
     
  20. xoofx

    xoofx

    Unity Technologies

    Joined:
    Nov 5, 2016
    Posts:
    206
    Note that Jon edited its original post pointing that Unity.Mathematics might be the only library that would deviate from the C# guidelines. We don't have currently a plan to change the overall shape of Unity.Mathematics to match these C# guidelines.

    Let me reiterate the rationale:

    Unity.Mathematics is not a library per se but should be seen as an additional types foundation that is making vector types as *first-class types in Unity* (like `int` `float`...etc.) as it is done for a shading language like HLSL for example, for both the language and runtime - via burst:

    • Use of lowercase name for types (`float4`, `float3`...etc.). At the core of the compilation, they are treated as low-level types as `int`, `float` are treated.
    • Use of lowercase for swizzles (e.g `myVec.xyz`) and field access (e.g `myVec.x` )
    • Use of lowercase for math functions operating on these vector types (e.g `dot` `mul`...etc.) to better match HLSL like concise syntax
     
    SirIntruder and recursive like this.
  21. Peter77

    Peter77

    Joined:
    Jun 12, 2013
    Posts:
    4,120
    I believe once there is a library allowed to deviate, others will follow. Just like the broken window theory works.
    I understand that and it does make sense. However, float is just a shortcut for System.Single and you probably don't have that "Unity.Single3" type I guess. But I'm totally fine with lower-case types in this case, because I understand the intention.

    I would question this one in terms of your global goal to work towards the .NET standards. If you would use CamelCase in this case, it would be quite close to the .NET standard already, considering one thinks of float3 as a shortcut like float is for System.Single.

    This decision is hard to understand for me, maybe because you hold some information back. With the current information I have, there is no need to have HLSL-like syntax in C# land.

    I don't expect a majority of shader gurus suddenly start writing game code, because the new math library uses a familiar naming convention. I also don't expect the new math library being used completely out-of-context (aka standalone) to the rest of the game code base.

    I actually imagine game programmers start to adopt the new math library and incorporate it in their C# game code and then it feels very out of place, like a 3rd class citizen.
     
    Ziflin, TJHeuvel-net and dadude123 like this.
  22. TJHeuvel-net

    TJHeuvel-net

    Joined:
    Jul 31, 2012
    Posts:
    413
    @xoofx

    • Use of lowercase for math functions operating on these vector types (e.g `dot` `mul`...etc.) to better match HLSL like concise syntax

    Can you maybe expand on why your team considers this something to be desired? Because by doing this you are deviating from the standards the rest of the C# codebase has, we're obviously not used to this concise standard.

    Even for the actual 'first class types' their methods just follow the standards, for example `int.CompareTo`. Whatever a first-class-type is, i've never seen this term used in a C# context. If anything i agree with OP, that by deviating from the standard it looks less built in, less first-class.
     
    Last edited: Jun 19, 2018
    Ziflin likes this.
  23. dadude123

    dadude123

    Joined:
    Feb 26, 2014
    Posts:
    787
    @JonHUnity @xoofx

    Is this only something you guys want? Because I'm not hearing any voices here that really want this new syntax.

    Yes, its more in line with hlsl, but is that even something we want in C#?

    I doubt that anyone will find it easier to work with C# just because the types and methods of one library are more like what they're used to.

    If anything, history has shown time and time again that missing consistency makes it harder for newcomers to get started.
     
  24. dadude123

    dadude123

    Joined:
    Feb 26, 2014
    Posts:
    787
    Look man I (and we, the community in general) just want to understand what is even going on here, so please don't take the following as an attack or something like that.

    Going forward from the points you lined out here: Ok! That sounds cool on paper, but what advantage does that actually have in the end? I for one have not heard programmers using Unity demanding "when will you finally make vectors first class types in unity!??!?"

    But what I do hear (here, and in other threads) is that people do not want to have yet another thing they have to get used to. I see a lot of people demanding better organization and more strict adherence to conventions.

    What possible gain could there be for the average unity programmer, or even for people coming straight from a shader-language?
    Is the only real purpose here to blur the lines between the languages? Is that a good thing even? (I think it is a terrible thing)

    I feel you, I'm coming from a different language than C# as well, and it sounds cool to "get the best of both worlds", but my experience in the past was that in the end you won't really feel at home in this new language-mix. All the seams and gaps where the syntax or convention changes are just a constant reminder of something half-baked.

    Swizzles are a great thing and are a compatible extension to C#, lowercase field access is not something people will be offended by very much either. But forcefully pressing hlsl shaped methods like "dot", "mul", ... into C#-shaped holes (the whole ecosystem here) is not going to get a great reception except maybe for the hand full of people who told you it was a good idea (as you can clearly see from this thread)

    Is it just making unity more accessible for people coming from shading languages?
    Why do they need special treatment (so much that even C# programmers who use jobs/ECS have to suddenly adhere to new conventions)?
    Those are very intelligent people as well, I'm certain they won't be confused by differently named functions for long.
    But I guarantee that more people will be confused by having methods that suddenly go against all the C# conventions they're used to.

    So please, explain to us how this massively different convention is supposed to make unity better for the masses.
     
    Ziflin and Peter77 like this.
  25. xoofx

    xoofx

    Unity Technologies

    Joined:
    Nov 5, 2016
    Posts:
    206
    Let me try to explain why we want this but please, I'm not talking for myself here, I may disagree with some particular points actually but I'm trying to reflect as much as possible the diverse views at Unity on the "why" underlying of this naming convention.

    First you are aware that Unity is working on bringing AAA features to the whole platform on many levels (and the work on ECS and burst is part of this goal). In order to attract this new audience, we would like to provide a library that is closer to what regular C++ & Graphics developers are used to. To highlight what is the impact in practice, @mike_acton who has been working for years for AAA studios added a few noise functions to Unity.Mathematics (not released yet), that he converted from here https://github.com/stegu/webgl-noise/blob/master/src/cellular2D.glsl to https://github.com/Unity-Technologi...ter/src/Unity.Mathematics/Noise/cellular2D.cs and he was very happy with this experience of being able to use a syntax he is very familiar with. You can have look, and you will see that the code is just very similar to the original version and super easy to work with.

    Secondly, there is an underlying broader goal between shading language and C# at Unity where we would like to provide a much higher level language experience when developing shaders (bringing many features that we don't have today with shading languages). The fact is that this experience requires quite often a tight integration between your shading language and your language pushing data to it (i.e C# typically you want to express some computation that could happen either on the CPU before pushing to the GPU, or not), and we are hoping that we will come in the coming years with an integrated experience likely through C# where you can seamlessly write very efficient intermixed CPU/GPU code (plus all the extra benefits of generics, tools refactoring...etc.). There was even a small effort for prototyping this during last year Unity Hackweek. Burst has been developed with this ultimate goal in mind, while we are still today only targeting the CPU side of the problem. There is a long, long way to go to get there, but this is something we are actually forecasting. Having a very similar syntax here is key to ease bridging this two world together.

    I (and now I'm talking with my sole opinions) have been developing for years in C#, I'm quite very attached to C# naming conventions, I have released a bunch of C# OSS and private projects and I have always been following them. But, as I have also done a bunch of graphics programming, including developing a powerful shading language on top of HLSL that was similar to C#, I'm entirely ok to drop the "naming conventions god" if we can get a powerful and accessible game programming experience with Unity. And I really don't think that a naming convention is a stop gap for that, considering that we want to go beyond what C# means today for game programming.
     
    Last edited: Jun 20, 2018
  26. hippocoder

    hippocoder

    Digital Ape Moderator

    Joined:
    Apr 11, 2010
    Posts:
    25,618
    Very fair points, thanks for kindly taking the time to explain above and beyond the call of duty. I think people will definitely appreciate that.