Welcome, Guest. Please login or register.

Author Topic: New naming convention  (Read 36627 times)

0 Members and 1 Guest are viewing this topic.

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 31730
    • View Profile
    • SFML's website
    • Email
New naming convention
« on: January 07, 2012, 06:41:09 pm »
Hi

Although I've always been against it, and still thinks that it's an insane decision, I did it.

Here are the new conventions:
- functions and public variables use the camelCase notation
- getters have no more get/is prefix

I've also changed class members: they use the 'm_' prefix instead of 'my' -- but this one has no impact on user code.

I did it mainly because:
- I didn't like the previous conventions anymore
- it's closer to the current global trend
- it makes functions like begin(), clear(), etc. compatible with std notation
- it allows a less verbose and globally nicer syntax

I'm really sorry for users who have a big amount of code based on SFML, or people who are using the same convention as me for their own library (SFGUI, Thor, ...). Feel free to complain or insult me :D

The good thing is that after pushing this modification (monday), I'll commit the new time API and SFML 2.0 can then be officially considered finished. And I promise, SFML 2.0 will be the beginning of a stable, robust and mature API.
Laurent Gomila - SFML developer

Nexus

  • SFML Team
  • Hero Member
  • *****
  • Posts: 6119
  • Thor Developer
    • View Profile
    • Bromeon
Re: New naming convention
« Reply #1 on: January 07, 2012, 06:44:59 pm »
Quote from: "Laurent"
I'm really sorry for users who have a big amount of code based on SFML, or people who are using the same convention as me for their own library (SFGUI, Thor, ...). Feel free to complain or insult me :D
I think we will have enough opportunities to do this, once we start converting everything :D
Probably, I am going to adapt my convention, since Thor is an extension and my API is often very similar to SFML's. For SFGUI and other libraries, this looks differently.

It's indeed a little bit insane, but I'm curious how this will affect coding with SFML... ;)

By the way, did you use some script/regex/... for the renaming or have you just had too much free time recently? :P
Zloxx II: action platformer
Thor Library: particle systems, animations, dot products, ...
SFML Game Development: first SFML book

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 31730
    • View Profile
    • SFML's website
    • Email
New naming convention
« Reply #2 on: January 07, 2012, 07:17:32 pm »
Quote
By the way, did you use some script/regex/... for the renaming or have you just had too much free time recently?

Since I spend most of my coding time thinking about design issues rather than actually writing code, I tend to like this no-brainer stuff. It took me only a few hours ;)
Laurent Gomila - SFML developer

Tank

  • SFML Team
  • Hero Member
  • *****
  • Posts: 1461
    • View Profile
    • Tank's Blog
    • Email
New naming convention
« Reply #3 on: January 08, 2012, 07:48:27 am »
Oh noes, Java-like function names. ;) (I've never got used to them, but that's personal preference).

It will be interesting for SFGUI. I wanted to drop CamelCase some day anyway, but I did not plan to move over to doThat actually. In my own projects I'm using lower_case (like the stdlib) and that will probably also be applied to SFGUI.

But in general: Good that you did it. Now it's time for some 'sed' runs. ;)
SFGUI: Simple and Fast GUI library for SFML
Game Development Design articles
IRC: #sfml @ irc.boxbox.org

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 31730
    • View Profile
    • SFML's website
    • Email
New naming convention
« Reply #4 on: January 08, 2012, 09:01:27 am »
Quote
In my own projects I'm using lower_case (like the stdlib) and that will probably also be applied to SFGUI.

I've read *many* blog articles and forum threads about camelCase vs lower_case, and I found that many developers have strong arguments against lower_case. That's why I ended up with camelCase.

Quote
But in general: Good that you did it

Oh, I didn't expect such a reaction :D
Why do you think that it's good?
Laurent Gomila - SFML developer

Grimshaw

  • Hero Member
  • *****
  • Posts: 631
  • Nephilim SDK
    • View Profile
New naming convention
« Reply #5 on: January 08, 2012, 10:18:31 am »
I loved the change! It will be absolutely worth it to adapt to this new change.. I've always been used to this convention, but when coding my games, there was such a big mix of different conventions..

Now everything can be looking the same, which is great :)

texus

  • Sr. Member
  • ****
  • Posts: 459
    • View Profile
    • TGUI
    • Email
New naming convention
« Reply #6 on: January 08, 2012, 10:18:35 am »
Quote
functions and public variables use the camelCase notation

So the class names are still the same, right?
TGUI: C++ SFML GUI
TGUI.Net: C# binding for TGUI

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 31730
    • View Profile
    • SFML's website
    • Email
New naming convention
« Reply #7 on: January 08, 2012, 11:28:01 am »
Quote
So the class names are still the same, right?

Yep.
Laurent Gomila - SFML developer

Marukyu

  • Newbie
  • *
  • Posts: 34
    • View Profile
New naming convention
« Reply #8 on: January 08, 2012, 03:25:42 pm »
Now that's going to be a lot of code to rewrite and it'll take a while for me to get used to it. ~_~
Hopefully I'll find a way to do this with regular expressions. I could never figure out how to use sed, a little help with this would be appreciated. :)

aquanull

  • Newbie
  • *
  • Posts: 6
    • View Profile
New naming convention
« Reply #9 on: January 08, 2012, 03:55:22 pm »
Wow, I didn't expect to have my first post here in this fashion, but:

Quote from: "Laurent"
I did it mainly because:
- I didn't like the previous conventions anymore
- it's closer to the current global trend
- it makes functions like begin(), clear(), etc. compatible with std notation
- it allows a less verbose and globally nicer syntax

Most of the reasons are lousy. In detail:

"- I didn't like the previous conventions anymore"
The only sane reason. So you consider something that you have always been against better than something you didn't like? :roll:

"- it's closer to the current global trend"
By "the current global trend" you mean the more confusing javaCase and Get-/Is- omission? But look, you hear they talking about something like "HTML5 is taking over ground and will dominate the industry and thus HTML5 IS THE FUTURE and the world is moving towards it" so it is HTML5 that is "the global trend", isn't it? If so, why not modify the lib for HTML5?
Oh, were they also talking about something like "JVM/.Net/Ajax/<INSERT_RANDOM_TECH_HYPE> IS THE FUTURE"? Never mind. :twisted:

"- it makes functions like begin(), clear(), etc. compatible with std notation"
Are they compatible with std usage? If not, why should they impersonate something just different? And again, this javaCase != the dreaded lower_case naming convention that std uses, so that's not a success. :wink:

"- it allows a less verbose and globally nicer syntax"
How could changes in the naming convention affect the syntax? You don't mean to use some grotesque C preprocessor # macro tricks for an alternative syntax, do you? :shock:

Seriously, there is a reason (might seem weak but still standing) for me to oppse the javaCase + omitted-Get-/Is- notation for functions:
Code: [Select]

class A
{
public:
    // camelCase + omitting Get-
    int publicProperty0;
    int &publicProperty1() { return m_value1; }
    int publicProperty2;
    // PascalCase and I actually like it for function naming
    int &GetPublicProperty1() { return m_value1; }
    int GetPublicPropertyCount() { return 3;}
private:
    int m_value1;
};

void foo()
{
    using namespace std;

    A someVar; // I always use camelCase for variable names

    cout << someVar.publicProperty0 << endl;
    cout << someVar.publicProperty1 << endl; // SYNTAX ERROR thanks to misleading name
    cout << someVar.publicProperty1() << endl; // OK but inconsistent syntax
    cout << someVar.publicProperty2 << endl;
    cout << someVar.GetPublicProperty1() << endl; // OK
    cout << someVar.GetPublicPropertyCount() << endl; // OK and consistent
}

class B
{
public:
    bool empty(); // Is- omitted, so guess what this does - remember STL's similar flaw?
    bool Empty() { return m_container.remove_all_elements() == SUCCESS_OK; } // you see?
    bool IsEmpty() { return m_container.count_elements() == 0; }
private:
    SomeContainer m_container;
};


As you may see, since C++ doesn't support C#-ish properies, it has to use member functions whose invoking syntax is different from C#-ish properties', and trying to mimic that imperfectly may lead to syntax (class A example) and sematic (class B example) errors.  Further more, AFAIK, many C++ coding standards require that every function name should contain a verb. So I don't think this naming convention change (except that of class internal members) is the right move.

Still, it's good to know that SFML 2.0 has finally been finished (or close to finished if you are going to change the naming convention again after reading this post). Good job! :D

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 31730
    • View Profile
    • SFML's website
    • Email
New naming convention
« Reply #10 on: January 08, 2012, 06:44:45 pm »
Quote
"- I didn't like the previous conventions anymore"
The only sane reason. So you consider something that you have always been against better than something you didn't like?

This decision is insane, but once it's done I'll feel much better when working on SFML. So yes, in this case I'm ready to do something that I've always been against.

Quote
By "the current global trend" you mean the more confusing javaCase and Get-/Is- omission? But look, you hear they talking about something like "HTML5 is taking over ground and will dominate the industry and thus HTML5 IS THE FUTURE and the world is moving towards it" so it is HTML5 that is "the global trend", isn't it? If so, why not modify the lib for HTML5?

By "global trend" I really mean global trend: ie. what most people use. You may not like it, but it is what people prefer on a global scale.
And that was not the reason why I changed, I never do something just because other people do it . But now that it's done, it's a good argument ;)

Quote
"- it makes functions like begin(), clear(), etc. compatible with std notation"
Are they compatible with std usage?

Of course they are.

Quote
And again, this javaCase != the dreaded lower_case naming convention that std uses, so that's not a success.

Fortunately, the functions that need to be compatible with std notation only contain one word, so they look the same as if I were using lower_case notation.

Quote
"- it allows a less verbose and globally nicer syntax"
How could changes in the naming convention affect the syntax?

I just meant that code that uses SFML now looks less verbose and nicer. I don't know what you mean with your "preprocessor macros tricks".

Quote
As you may see, since C++ doesn't support C#-ish properies, it has to use member functions whose invoking syntax is different from C#-ish properties', and trying to mimic that imperfectly may lead to syntax (class A example) and sematic (class B example) errors

Yes, that's why I try to use this notation in a "perfect" way. I never mix public variables and public functions in the same class (there's only one exception in the SFML API). However I admit that omitting is/get can lead to ambiguity because in english, a verb and its corresponding noun can be identical. But that's not a big issue to me, once you know what the function does, or if you read the doc / tutorials before coding, everything should be ok.

Quote
Further more, AFAIK, many C++ coding standards require that every function name should contain a verb

Not mine, fortunately :)

Quote
Still, it's good to know that SFML 2.0 has finally been finished (or close to finished if you are going to change the naming convention again after reading this post).

Don't tempt me, it was really hard for me to take this decision ;)

Thanks for your detailed feedback.
Laurent Gomila - SFML developer

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 31730
    • View Profile
    • SFML's website
    • Email
New naming convention
« Reply #11 on: January 08, 2012, 06:49:47 pm »
I forgot one thing: this naming convention (except the omission of the "is" prefix) is taken from the Qt library, which is a huge library used by a huge amount of developers, and I think that it works pretty well for them so far. I'm not inventing anything.
Laurent Gomila - SFML developer

Groogy

  • Hero Member
  • *****
  • Posts: 1470
    • MSN Messenger - groogy@groogy.se
    • View Profile
    • http://www.groogy.se
    • Email
New naming convention
« Reply #12 on: January 08, 2012, 07:34:00 pm »
I hope you sneezes every-time I swear at your name xD

No it's not that bad, it could be worse. You could have used snake notation or even worse... HUNGARIAN!? At least it was something sensible.

Anyway imagine something like.. Every half-hour between 18:00 to 00:00 me yelling loudly: "DAMN YOU LAURENT!" waving my hand in the air.

Just for lulz :D
Developer and Maker of rbSFML and Programmer at Paradox Development Studio

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 31730
    • View Profile
    • SFML's website
    • Email
New naming convention
« Reply #13 on: January 08, 2012, 07:43:23 pm »
Yeah, I can easily imagine that. I was expecting it :D
Laurent Gomila - SFML developer

Grimshaw

  • Hero Member
  • *****
  • Posts: 631
  • Nephilim SDK
    • View Profile
New naming convention
« Reply #14 on: January 08, 2012, 08:07:07 pm »
I used Qt massively too, and it worked just fine for me, this change makes all the sense.. Not that it was bad before, but there is room for improvement..

Nice work Laurent! And good job on sfml2 , on what it became so far, i was impressed when i updated it yesterday!