Welcome, Guest. Please login or register. Did you miss your activation email?

Author Topic: New naming convention  (Read 89848 times)

0 Members and 1 Guest are viewing this topic.

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 32504
    • View Profile
    • SFML's website
    • Email
New naming convention
« Reply #45 on: January 13, 2012, 12:22:49 pm »
Quote
I doubt that's your reason. Else stick to lowercase everywhere.

That's one of the reasons.
Since it seems widely accepted that class naming must be different from function/variable naming, we still need some uppercase.

Quote
So constants will be "fooBar", too? Eek..

Hmm no, constants will be "FooBar", so it's still the same as before (that's what I said above) and they are named like classes (that's what you thought the new convention would "solve" -- and it doesn't) ;)

Quote
I wouldn't care of comments like "I don't like it, it's ugly!!!", just have good reasons to switch and everything's fine. After switching and another month everybody won't care anymore..

I know, and I don't take "I like/don't like" arguments in account. But there are also good arguments on both sides.
Laurent Gomila - SFML developer

Klaim

  • Full Member
  • ***
  • Posts: 137
    • View Profile
New naming convention
« Reply #46 on: January 13, 2012, 03:44:33 pm »
Laurent, can you point me to the articles agains this_notation online? Last time I searched I was finding lot of people saying it's more readable and forced the writer to be concise (because it big faster).

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 32504
    • View Profile
    • SFML's website
    • Email
New naming convention
« Reply #47 on: January 13, 2012, 04:28:31 pm »
Quote
Laurent, can you point me to the articles agains this_notation online? Last time I searched I was finding lot of people saying it's more readable and forced the writer to be concise (because it big faster).

I'll try to find them back.

As far as I remember, arguments against lower_case were that while it is easier to see word boundaries inside an identifier, it is harder to see identifier bounds. An extreme example that I've seen:
Code: [Select]
the_third_number=the_first_number-the_second_number;

People often say that if you convert a text to lower_case it's more readable than camelCase. Which is true, but code is not text. What must catch the eye is identifiers, not individual words.

That's what I've read -- not my personal opinion.
Laurent Gomila - SFML developer

Mikademus

  • Newbie
  • *
  • Posts: 31
    • View Profile
New naming convention
« Reply #48 on: January 13, 2012, 11:25:23 pm »
Let's be logical.

1) Consistency is the paramount item of importance. SFML today isn't consistent (f.i. the rect and vector members, which drives f.i. me to distraction).
2) Changing anything for consistency will break code.
3) If breaking code, it is better to make everything consistent while at it rather
than retain inconsistencies or break a bit more with every update.
4) SFML2 is already broken versus 1.6 and many previously installed 2.0 builds. Therefore, there is no better time to fix what needs to be done than now since clients will need to redress their code for 2.0 compatibility anyway.

That is logical. Now, let's change to subjectives, popular impressions and trends.

SFML's current PascalCase is actually a common (as in "occurring" rather than ubiquitous) argument against it, as in when questions about pros and cons of different systems are asked on fora, the code convention of SFML is a recurring drawback.

Compared to the vast majority of current and widespread middleware solutions the convention is apart and SFML code stands out as deviant against other code in a project pulling in several libraries. This goes against the principle of consistency. Just as Laurent says, the trend is definitely for Class::camelCase, void Class::camelCase() and void CamelCase() code formatting.

From a pedagogical perspective, camelCase creates clear and immediate visual distinctions between classes, members, methods and free functions.


For me, Laurent's announcement was a very welcome birthday present, and from a non-subjective perspective I think it is a the correct way forward.

Klaim

  • Full Member
  • ***
  • Posts: 137
    • View Profile
New naming convention
« Reply #49 on: January 14, 2012, 10:06:39 pm »
Quote from: "Laurent"
Quote
Laurent, can you point me to the articles agains this_notation online? Last time I searched I was finding lot of people saying it's more readable and forced the writer to be concise (because it big faster).

I'll try to find them back.

As far as I remember, arguments against lower_case were that while it is easier to see word boundaries inside an identifier, it is harder to see identifier bounds. An extreme example that I've seen:
Code: [Select]
the_third_number=the_first_number-the_second_number;

People often say that if you convert a text to lower_case it's more readable than camelCase. Which is true, but code is not text. What must catch the eye is identifiers, not individual words.

That's what I've read -- not my personal opinion.


Yes I understand, let's be courteous about it.

That's interesting because I have another rule that I use in all languages that makes this problem not be a problem : always bound operators with spaces (even in Python) :

Code: [Select]
the_third_number = the_first_number - the_second_number;

Make things more readable in general. Another rule that I use most of the time is to always put spaces after ( or { or [ and before ) or } or ] . That way :

Code: [Select]
the_numbers[ 2 ] = the_numbers[ 0 ] - the_numbers[ 1 ];

Also, I find that knowing that the graphic size of the name will grow fast with more words, it helps getting more to the point (often not more than 2 words) :

Code: [Select]

numbers[ 2 ] = numbers[ 0 ] - numbers[ 1 ];

auto k = build_variant( numbers );
k.clear();
k.resize( 42 );



Anyway, as far as you keep a consistent code formatting policy, I'm happy :)

mateandmetal

  • Full Member
  • ***
  • Posts: 171
  • The bird is the word
    • View Profile
    • my blog
New naming convention
« Reply #50 on: January 14, 2012, 10:16:27 pm »
I think the "Is/Get" syntax makes SFML more easy to learn for the beginners
- Mate (beverage) addict
- Heavy metal addict _lml
- SFML 2 addict
- My first (and free) game: BichingISH!

Svenstaro

  • Full Member
  • ***
  • Posts: 222
    • View Profile
New naming convention
« Reply #51 on: January 17, 2012, 04:36:56 am »
I support Laurent's proposed changes for his exact reasoning. I use a lot of Qt and it would make my code feel more consistent.

Sind

  • Newbie
  • *
  • Posts: 2
    • View Profile
New naming convention
« Reply #52 on: January 17, 2012, 05:35:00 pm »
Just dropping by to state that I support using camelCase.
Though no, I don't actually have any proper argument as to why, other than that I prefer it <.<

Oberon

  • Newbie
  • *
  • Posts: 19
    • View Profile
    • My Github profile
New naming convention
« Reply #53 on: January 17, 2012, 06:19:45 pm »
Hah! :D I finally found a very practical reason for camelCase!
Code: [Select]
#include <Windows.h>
Every WinAPI function is #defined so that namespaces, scope, etc. are rendered useless. For example the really existing code
Code: [Select]

#ifdef UNICODE
#define GetTextMetrics  GetTextMetricsW
#else
#define GetTextMetrics  GetTextMetricsA
#endif // !UNICODE

will change the hypothethically code myText.GetTextMetrics() to myText.GetTextMetricsW() (or myText.GetTextMetricsA()), causing compiler or linker errors or "function not found in DLL" errors.
There are also lots of other dangerous names like LoadImage, LoadIcon, PeekMessage, ...
So if SFML's names do not clash with them, user code which does not want to mix in yet another naming style might get problems when using native WinAPI.
Microsoft uses PascalCase everywhere (except for the infamous min/max macros) so with camelCase SFML users wouldn't face this problem.

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 32504
    • View Profile
    • SFML's website
    • Email
New naming convention
« Reply #54 on: January 17, 2012, 06:23:25 pm »
Most (if not all) SFML users won't use the Windows API directly. And SFML does its best to avoid including <windows.h> in its own public headers.
Laurent Gomila - SFML developer

Oberon

  • Newbie
  • *
  • Posts: 19
    • View Profile
    • My Github profile
New naming convention
« Reply #55 on: January 17, 2012, 06:38:45 pm »
I think using native Windows API and SFML together is not that uncommon: For example, if I wanted to program a screensaver in SFML I had to use WinAPI, because for the preview I get a window handle which I have to use as the parent for my window.

To illustrate:
(random screenshot found with Google).
In this image, the program "ScreenOGL.scr" was started with eg. /p:12345, where 12345 is the handle of the parent window.

And after all, there is even the win32 example included in SFML.

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 32504
    • View Profile
    • SFML's website
    • Email
New naming convention
« Reply #56 on: January 17, 2012, 06:46:34 pm »
How many of the SFML users are developing a Windows screensaver? ;)

There might be developers that mix Win32 and SFML, but they are a very little minority, so this argument in favor of camelCase is not really significant.

And how many SFML functions collide with Windows ones? Probably none.
Laurent Gomila - SFML developer

Beta_Ravener

  • Jr. Member
  • **
  • Posts: 51
    • ICQ Messenger - 271426715
    • View Profile
New naming convention
« Reply #57 on: January 17, 2012, 11:30:09 pm »
What about different view angle?
Ask a question, what notation you were teached? I could find just two naming conventions for C++: some_function and SomeFunction. The first is used by standard and we can find this convention also in cplusplus.com tutorials. The later is wide-spread in c++ books, but there are still some that stick with some_function. But I never saw anyone teaching camelCase notation. It seems to me as a crazy attempt to shorten some_function.

My argument would be that in my case I use openGL alot with SFML. Their notation is based on camelCode, but the first word is always gl, rendering the rest as CamelCode notation. When writing wrappers around some openGL functions, it was always convenient just to omit gl. It's still my personal preference though.

As already wrote, ambiguity will always exist by not using underlines.. either between classes and functions or functions and variables. There's no gain in changing this. QT have strong user base, but so does have SFML and many projects that decided to align with it's style. It's not a question of laziness, but of wasted time that could be spent better (as with the time I spent to write this  :) ). SFML might change it's notation, but I'll be really interested in how other projects will answer to this issue. And I'm fully aware that SFML 2.0 is only for testing and indeed some changes break the code every time, but this will be huge.

As for the gets/is/sets the advantage of uniform working with member data is too small as it can be compared with fast navigation in intellisense/discovery/(whatever..), but there is great comprehensive value in those few characters. If we'd like to go down to standard we should really think about what bastien posted about quasi classes. Indeed the std::string has .length() and not .GetLength(), but it doesn't use .length(int newLength) [as opposed to .SetLength() ]  but .resize() . I think omitting those few characters will just confuse people, and add more visits to your site  :D

Bobomite

  • Newbie
  • *
  • Posts: 3
    • View Profile
New naming convention
« Reply #58 on: January 18, 2012, 01:06:19 am »
I am a novice to C++ and I'm using SFML to learn and found that it's powerful enough I'm just going to focus on making 2D games for now.

Coming from a web development background, I will definitely say that the move to camelCase is something I like a lot, we use that for everything at work in JavaScript.  Personally I find it easier on the eye than the alternatives.

As to removing get/set I actually liked that I knew what the function did by name and not by what t passed.  But I don't consider that a problem either way, because to use the function I need to have a reason/know why I am using it and by default if I am passing in (say) a Vector2d I am almost certainly setting it anyway.

And I'm lucky in that cleaning all my code will probably take like 20min tops.

mateandmetal

  • Full Member
  • ***
  • Posts: 171
  • The bird is the word
    • View Profile
    • my blog
New naming convention
« Reply #59 on: January 19, 2012, 04:27:05 am »
Quote from: "Laurent"
...And SFML does its best to avoid including <windows.h> in its own public headers.


 8)  8)  8)
- Mate (beverage) addict
- Heavy metal addict _lml
- SFML 2 addict
- My first (and free) game: BichingISH!