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

Author Topic: SFML2 API concerns  (Read 10201 times)

0 Members and 1 Guest are viewing this topic.

Recruit0

  • Jr. Member
  • **
  • Posts: 66
    • View Profile
SFML2 API concerns
« on: June 24, 2010, 01:24:02 am »
I noticed while looking at the current API const-correctness is not followed. As the current API can't really be changed to fix this (without potentially causing problems) Please make SFML2 const-correct when it's released. Examples:

String (char ansiChar)
String (const char *ansiString)
String (const wchar_t *wideString)

Should be:

String (const char ansiChar)
String (const char * const ansiString)
String (const wchar_t * const wideString)

For more information: http://www.parashift.com/c++-faq-lite/const-correctness.html#faq-18.3

Also:

String (const Uint32 *utf32String)

I'm wondering what the purpose of Uint32 is since there's already a uint32_t defined in the standard library (stdint.h), http://en.wikipedia.org/wiki/Stdint.h

Nexus

  • SFML Team
  • Hero Member
  • *****
  • Posts: 6286
  • Thor Developer
    • View Profile
    • Bromeon
SFML2 API concerns
« Reply #1 on: June 24, 2010, 02:39:09 am »
Top-level cv-qualification at function parameters is completely useless. Actually, it doesn't even contribute to the function type.

The second const at
Code: [Select]
const char* constspecifies that the pointer itsself is immutable, which brings no benefit since it is copied to the function anyway.

Never declare copied value parameters of functions const. Doing so spills the API with irrelevant information, while having no advantage at all. Considering const-correctness means to make sure that references and pointers point to const-qualified objects where meaningful, rather than that they are const-qualified themselves. References are already immutable by definition.

Therefore, the shown SFML examples are perfectly const-correct, and there is nothing to fix.

Concerning uint32_t, this type is not part of the C++ standard library (in fact, the header <stdint.h> is not, either). Apart from that, a direct use of it (without typedef and namespace) would hurt the naming convention and the uniform interface of SFML.
Zloxx II: action platformer
Thor Library: particle systems, animations, dot products, ...
SFML Game Development:

Recruit0

  • Jr. Member
  • **
  • Posts: 66
    • View Profile
SFML2 API concerns
« Reply #2 on: June 24, 2010, 03:53:46 am »
I understand what "const <type>* const" means.

I took const-correct as "if the object doesn't need to be modified, then it must be const." This way the object's behaviour is more defined.

As for benefits, the developer could inadvertently introduce a bug into the system without knowing by accidentally allowing the pointer to change even though it shouldn't. Any (bug) locking mechanisms should be used even if you think you know what you're doing (i.e. don't assume there's nothing wrong with your code). It can also prevent time wasted debugging code. That's what I believe is const-correct (i.e. const isn't a keyword you use when you don't want something to change, it's a keyword you use when something isn't going to change).

I didn't say C++ standard library. By <stdint.h> it's clear I'm refering to C99. How would using it hurt the naming convention/uniform interface of SFML? (It's already using wchar_t...)

Laurent

  • Administrator
  • Hero Member
  • *****
  • Posts: 32504
    • View Profile
    • SFML's website
    • Email
SFML2 API concerns
« Reply #3 on: June 24, 2010, 08:35:52 am »
SFML is const-correct. Doing what you suggest would just be additional protection for the developer (it wouldn't change anything for the end user), but in "real-life" it is rarely used because it is not really relevant.

Quote
I didn't say C++ standard library. By <stdint.h> it's clear I'm refering to C99

Too bad SFML is not written in C... ;)
Laurent Gomila - SFML developer

Nexus

  • SFML Team
  • Hero Member
  • *****
  • Posts: 6286
  • Thor Developer
    • View Profile
    • Bromeon
SFML2 API concerns
« Reply #4 on: June 24, 2010, 09:41:18 am »
Quote from: "Recruit0"
I took const-correct as "if the object doesn't need to be modified, then it must be const." This way the object's behaviour is more defined.
One can follow your suggestions in the implementation (function definition), but never in the interface (declaration). It is an implementation detail whether the function plans to change the copied parameters or not, that's why we are not talking about an API concern. A top-level const appearing in the documentation doesn't provide any relevant information to the user. It's even worse, the const is likely to arise confusion and to deflect from important things.

The reason why only a small part of the C++ programmers qualifies copied parameters const is that it has mostly no noteworthy additional value.

Quote from: "Recruit0"
I didn't say C++ standard library. By <stdint.h> it's clear I'm refering to C99. How would using it hurt the naming convention/uniform interface of SFML? (It's already using wchar_t...)
C++ is not backward-compatible to C99, therefore this is no option. It would hurt the uniformity if there were types sf::Uint8, sf::Uint16, but a global ::uint32_t.
Zloxx II: action platformer
Thor Library: particle systems, animations, dot products, ...
SFML Game Development:

pdusen

  • Newbie
  • *
  • Posts: 30
    • View Profile
SFML2 API concerns
« Reply #5 on: June 24, 2010, 01:31:43 pm »
Quote from: "Nexus"
A top-level const appearing in the documentation doesn't provide any relevant information to the user. It's even worse, the const is likely to arise confusion and to deflect from important things.


...You know a programmer who gets confused by the word "const"?

Quote
The reason why only a small part of the C++ programmers qualifies copied parameters const is that it has mostly no noteworthy additional value.


What's your basis for believing that? It's been my experience that C++ programmers generally go out of their way to const-qualify when a passed value won't be changed, copy or not.

Hiura

  • SFML Team
  • Hero Member
  • *****
  • Posts: 4321
    • View Profile
    • Email
SFML2 API concerns
« Reply #6 on: June 24, 2010, 01:46:41 pm »
Quote from: "pdusen"
Quote from: "Nexus"
A top-level const appearing in the documentation doesn't provide any relevant information to the user. It's even worse, the const is likely to arise confusion and to deflect from important things.


...You know a programmer who gets confused by the word "const"?

Yup, mainly beginners but…

Quote
It's a common belief that const-correctness helps compilers generate tighter code. Const is indeed a Good Thing, but the point of this issue of GotW is that const is mainly for humans, rather than for compilers and optimizers. When it comes to writing safe code, const is a great tool that lets programmers write safer code with compiler checking and enforcement. Even when it comes to optimization, const is still principally useful as a tool that lets human class designers better implement handcrafted optimizations, and less so as a tag for omniscient compilers to automatically generate better code.
from http://www.gotw.ca/gotw/081.htm

also interesting reading : http://www.gotw.ca/gotw/006.htm
SFML / OS X developer

Nexus

  • SFML Team
  • Hero Member
  • *****
  • Posts: 6286
  • Thor Developer
    • View Profile
    • Bromeon
SFML2 API concerns
« Reply #7 on: June 24, 2010, 03:09:51 pm »
Quote from: "pdusen"
...You know a programmer who gets confused by the word "const"?
Not in general, but it partially obscures situations and requires more time to understand a context. The problem of overusing a language feature is that you don't differ anymore between important and useless cases.

In my opinion, a crucial point in designing a robust API entails making interfaces as expressive as possible already by language features, one of which is const. I primarily make sure that function interfaces are const-correct. In other words: I keep const for the important uses, so that I immediately see respective semantics. The expressiveness decreases when I use const wherever possible.

Which doesn't mean I don't declare other variables const. However, I only do it when it really brings an advantage. A counter-example:
Code: [Select]
class Person
{
    public:
        Person(const std::string& name, const Date& birthDate);

    private:
        std::string myName;
        const Date myBirthDate; // can't ever change, so make it const
};
Nice, by writing that single const I've just now disabled Person's value semantics and prevented Person objects from ever being stored inside STL containers. It's important that not every const increases const-correctness and that some – to the contrary – even result in bad effects, of which the increasing complexity is only the most obvious one.

There is another problem: consistency. Would you place a const here?
Code: [Select]
void MyClass::SetValue(const int value)
{
    // prevent value from accidentally being modified
    myValue = value;
}
If not, why not? Because the function is too trivial? Yes, but that applies to many functions. Where do you place the border? And what if you declare SetValue() inline? Then the interface is again spilled with useless information.


Quote from: "pdusen"
What's your basis for believing that? It's been my experience that C++ programmers generally go out of their way to const-qualify when a passed value won't be changed, copy or not.
It's my experience from looking at code. SFML is such an example, the C-library OpenGL is another one. I just skimmed through some Boost and MSVC++ StdLib headers, and I never saw a top-level-const in a function declaration.

Why isn't it relevant for you if the parameter is copied or not? You can't change the original value inside the function, and that's the only important thing for the caller. You can create thousands of further copies and modify them, the caller cannot prevent that. But he can prevent that his value is changed.

By the way, Herb Sutter seems to share my opinion.
Quote from: "[url
http://www.gotw.ca/gotw/006.htm[/url]"]Since the point object is passed by value, there is little or no benefit to declaring it const.
Normally const pass-by-value is unuseful and misleading at best.

Of course, the whole topic is also a matter of style. I personally like expressive code, and I don't like redundancy or irrelevant information. But we should at least agree that top-level const-qualifications in function declarations (not definitions) are meaningless.
Zloxx II: action platformer
Thor Library: particle systems, animations, dot products, ...
SFML Game Development:

pdusen

  • Newbie
  • *
  • Posts: 30
    • View Profile
SFML2 API concerns
« Reply #8 on: June 24, 2010, 07:29:54 pm »
Quote from: "Nexus"
Quote from: "pdusen"
...You know a programmer who gets confused by the word "const"?
Not in general, but it partially obscures situations and requires more time to understand a context. The problem of overusing a language feature is that you don't differ anymore between important and useless cases.


I don't necessarily think it's important to const-qualify in this case, but I think you're massively overblowing the impact of doing so on a user.

Quote
Quote from: "pdusen"
What's your basis for believing that? It's been my experience that C++ programmers generally go out of their way to const-qualify when a passed value won't be changed, copy or not.
It's my experience from looking at code. SFML is such an example, the C-library OpenGL is another one. I just skimmed through some Boost and MSVC++ StdLib headers, and I never saw a top-level-const in a function declaration.


I'd like to point out that OpenGL probably is that way because it's a C library and const wasn't in C when it was created.

Quote
Of course, the whole topic is also a matter of style. I personally like expressive code, and I don't like redundancy or irrelevant information. But we should at least agree that top-level const-qualifications in function declarations (not definitions) are meaningless.


I think it is really a style thing. My personal preference is, if I'm not modifying something, it becomes const, period. I see no reason to make an exception here for function parameters, or for pass-by-copy.

Nexus

  • SFML Team
  • Hero Member
  • *****
  • Posts: 6286
  • Thor Developer
    • View Profile
    • Bromeon
SFML2 API concerns
« Reply #9 on: June 24, 2010, 08:02:35 pm »
Quote from: "pdusen"
I don't necessarily think it's important to const-qualify in this case, but I think you're massively overblowing the impact of doing so on a user.
I think it depends on the user. If he works under a similar policy himself, he will probably be less confused, than if he strictly uses const in function parameters only for pointees and referencees. I also think you shouldn't underestimate the advantage of an expressive and consistent API.

Quote from: "pdusen"
I'd like to point out that OpenGL probably is that way because it's a C library and const wasn't in C when it was created.
The concept of constants was introduced to C long before OpenGL existed. OpenGL is still const-correct, as it uses the const keyword, too.

Quote from: "pdusen"
if I'm not modifying something, it becomes const, period. I see no reason to make an exception here for function parameters, or for pass-by-copy.
So how would you handle the Person example? It's never good to have such a rigid attitude. In programming, you should always be able to gauge the situation and to be flexible in respect of exceptions.
Zloxx II: action platformer
Thor Library: particle systems, animations, dot products, ...
SFML Game Development:

Recruit0

  • Jr. Member
  • **
  • Posts: 66
    • View Profile
SFML2 API concerns
« Reply #10 on: June 24, 2010, 08:36:25 pm »
No one was able to answer the question about uint32_t/etc so I googled some more. Apparently sf::<type> is more cross platform. On a side note, boost provides cstdint.hpp.

Quote
It's been my experience that C++ programmers generally go out of their way to const-qualify when a passed value won't be changed, copy or not.
I predicted people generally didn't throw const in there unless they remembered to (i.e. too rare rather than common). Although I guess if you're talking about working with other people in a company, I wouldn't know.

I could write paragraphs about const-correctness but I'd rather just drop the discussion here.

Nexus

  • SFML Team
  • Hero Member
  • *****
  • Posts: 6286
  • Thor Developer
    • View Profile
    • Bromeon
SFML2 API concerns
« Reply #11 on: June 24, 2010, 08:40:40 pm »
Quote from: "Recruit0"
No one was able to answer the question about uint32_t/etc so I googled some more. Apparently sf::<type> is more cross platform.
Actually, I answered it, and told you uint32_t wouldn't be part of the C++ standard library and could therefore not be used in SFML.
Zloxx II: action platformer
Thor Library: particle systems, animations, dot products, ...
SFML Game Development:

Recruit0

  • Jr. Member
  • **
  • Posts: 66
    • View Profile
SFML2 API concerns
« Reply #12 on: June 24, 2010, 08:47:38 pm »
Quote
I'm wondering what the purpose of Uint32 is

Nexus

  • SFML Team
  • Hero Member
  • *****
  • Posts: 6286
  • Thor Developer
    • View Profile
    • Bromeon
Re: SFML2 API concerns
« Reply #13 on: June 24, 2010, 08:56:40 pm »
Quote from: "Recruit0"
I'm wondering what the purpose of Uint32 is since there's already a uint32_t defined in the standard library
I understood your question in a way that you asked where the advantage of sf::Uint32 over ::uint32_t is. And I anwered that (standard-conforming and matching SFML's API).

If you generally wonder why there is a need for a 32 bit data type, the support for Unicode characters (UTF-32) is an example for a use case in SFML.
Zloxx II: action platformer
Thor Library: particle systems, animations, dot products, ...
SFML Game Development:

Recruit0

  • Jr. Member
  • **
  • Posts: 66
    • View Profile
SFML2 API concerns
« Reply #14 on: June 24, 2010, 09:45:59 pm »
Actually, the question (taken literally) means (to put it bluntly) "what's the difference?"

Someone could of well have asked "what's the purpose of SFML, there's already SDL which has been tried and tested (sort of de facto)" You don't answer that by listing API/etc, people typically spit out "oh it's faster, or oh it does this and this and this" i.e. They're not the same.

e.g. Why make a BMW <model> 2011? There's already a BMW <model> 2010? It's not because it's company policy. Which would be funny if you think about it: "Sir, it's company policy, Section 2 Code A, we have to make a new model every year". XD

 

anything