Exceptions in SFML 3 ?

[binary1248]

Simply put, this is what development of a small indie game would look like if you ask me (horrible diagram ):

Code: [Select]

            General idea of a game
                     ||
                     \/
More concrete idea of the game (basic design etc.)
                     ||
                     \/
   ------------> Write code
   |                 ||
   |                 \/
   |                Done? -- yes ------------------> Test
   |                 ||
   |                 no
   |                 ||
   |                 \/
   |- no -- Can't implement something?
   |                 ||
   |                yes
   |                 ||
   |                 \/
   |   Look for library to get things done
   |                 ||
   |                 \/
   |     Use library facilities in code <--------------------------
   |                 ||                                |          |
   |                 \/                                |          |
   -- yes -- Done using library?                       |          |
                     ||                                |          |
                     no                                |          |
                     ||                                |          |
                     \/                                |          |
         Don't know how to do something? -- yes --> read doc      |
                     ||                                           |
                     no -------------------------------------------
As strange as it sounds, the goal is to minimize the time spent using the library. The less time it takes to get something done with SFML the more time can be spent doing application specific coding, which if you ask me is the more rewarding part. Because of that, it shouldn't be offending if someone says they used "just" that one feature of SFML and they e.g. had an image loaded in 2 lines. If you want to write a conceptually "clean" library then you are free to do it, but it shouldn't be at the cost of the productivity of developers such as those from the horrible diagram above. Interfaces should be designed to reduce the time spent in both the "use library facilities in code" and "read doc" loops because it means that the overall time spent using the library will be minimized as well.

As Nexus already said, adding extra classes is a mental burden. I don't know anyone who finds an interface simpler the more classes it has... and classes can be anything in this case, including pure interfaces. The typical SFML user should have to create only that which they need and be able to do everything with that which they need. If you have a pure Image class, what could it do on it's own? It would have no information to start with, so an ImageLoader class would be nothing but pure boilerplate. You say you want to be able to customize the loading of resources? The C++ standard library already showed us how this is done: Traits. This is one of the things that makes C++ unique to other languages. The reason learning how to use the STL is that simple can be partially attributed to the usage of traits. For the newcomer to the language, they can get what they want done without caring one bit about them. For the advanced users who want to use memory pools, what do they do? They provide a specialized allocator and the job is done as well, without any noticeable difference for the beginners. The interface is not changed at all. I've become very keen on exploring traits more, especially with C++11 making more use of them than ever before. It would be interesting to see SFML make use of them in some way as well.

I think SFML evolution should be driven by what makes it more extensible while keeping it as simple as possible and minimizing boilerplate. The success of libraries and what drives people towards them is not how they are designed, but rather how fast and easily you can get things done with them.

I have great fun programming my own games and seeing how others have fun programming their own game as well. I know how frustrating it is when you are stuck on something that you know has to be done but has nothing to do with your original idea. And reading forum posts everyday, it seems that there are many common tasks that can still be simplified if you ask me. This is also the reason why I wrote a network library that takes care of object synchronization across multiple hosts. I had to do it in every single project I worked on, and judging by the network related posts I see, that is also what everyone else has to do all the time. This is an example of boilerplate, and it needs to go.

[MorleyDev]

My point way-back-when was simply that I find it conceptually simpler that an Image is simply an Image, all it does is be an Image and all it knows is how to be an Image. Not create one, not decode one from a PNG or JPEG file, just be an Image. People disagree, cool, I can accept that and understand why. I defend my opinion as reasonable but can understand the others and see that they too are reasonable.

Plus, I also acknowledge that the significant rewrite it would take would be presently more effort than gain. I feel that has caused some confusion, I may have not made it clear I've been having a theoretical conversation that I acknowledge has some practical limitations with the current system that would most likely make such a redesign more effort than it's worth.

Although with you're diagram...Well, I may be an odd duck since my first step when confused with a library usually isn't to browse the documentation but to browse the autocomplete and even the headers for something that looks useful and see if I can use that. If they fail, documentation is the next port of call before 'random googling in the hope someone posted something on a forum somewhere'.

EDIT: And I was in the middle of rewriting this, so...I guess I'll move it here. Exceptions!

I am being won over by the "two-interface" approach, main concern would be a lot of boilerplate code would get into SFML though and it'd be annoying to maintain.

I'm guessing there'd one implementation that outs the error, and one that passes through to that outed error and throws a different exception based on the error? Or the other way around? Actually I'd probably prefer the other way around, it lets SFML at least keep the advantages of exceptions internally even if that doesn't get exposed to the user who doesn't want them.

Either way, it seems like it could be a lot of boilerplate to do that for every function that could throw an exception.

[binary1248]

Maybe it's just me, but I see exceptions as things that can happen but really shouldn't.

The most disgusting code I have seen that uses exceptions was written in Java by a person I was studying with. They claimed that they didn't do bounds checking when iterating through a multidimensional array because they would use the exceptions that were thrown to navigate their broken loops. This is a case of "exceptions becoming the norm".

We mustn't forget, the reason they are called exceptions is because they present an exceptional case. One could argue that they are bound to be thrown at some point, but if you ask me, we should focus on preventing them from being thrown in the first place. An example: if you are scared of exceptions being thrown when loading a resource, consider why it would be thrown: if it doesn't exist as an example. How can you prevent it from throwing in this case? By making sure that the resource exists before you load it, through some other facilities.

You might think I use exceptions as a glorified fatal error mechanism, and you would be correct. If you are already ready to handle one that comes along, you could have spent that effort trying your best to prevent it before trying to load in the first place. I would call this "making exceptional behaviour into standard behaviour". If you want both cases to be viable and execution of the application to continue, do so in non-exception code. It makes it easier to understand that it is something that can happen and is nothing bad at all.

If I browse over code and see a try/catch somewhere I already know, "yeah something really bad and unexpected is going to happen somewhere around here" and that is not a feeling I'd like to live with. It's like walking through a city where everyone is wearing a gas mask as opposed to one that has a government that prevents dangerous chemicals from being recklessly disposed of (bad example I know but hopefully you get the point ).

[wintertime]

I'm not really into Java, but from an outside view it definitely looks like exceptions are tedious and overused in it. Especially cases when some standard library class throws some checked exception and you pretty much have to put a try/catch around it to rethrow something unchecked or modify the whole calltree. Or when every function in the call tree needs a try for cleanup, because stupid Java designers thought the only resource one would use was memory, but a garbage collector is not concerned with you for example not exhausting file handles while someday if you are lucky some finalizer runs.
In C++ this is a bit more sane, exceptions get used for really exceptional cases and if you do it right everything gets automatically cleaned up by RAII and destructors. A try block is a rare thing there, for when you know a second strategy to recover, to print some error message out in main or if you insist on wanting to play with insecure lowlevel things. But you can never fully prevent them, even if you check if a file is there beforehand there could theoretically be a bad sector on the HDD or the user could take out the CD or pull the USB connector or the server could stop answering or ...
Btw, I read some of the documentation of SFML recently and for some classes you get that long list of methods where only half of them are interesting to most people. There I really wished sometimes it was cut in two parts and I (or the library user just needing a little thing in that diagram) needed to concern myself only with one of those easily understood smaller parts.

[MorleyDev]

"Exceptions are for the exceptional". The blog post in the thread that spawned this one makes a good statement: They are best used in the situations where you did everything right, but it still didn't work because of situations largely out of your control or what could be reasonably expected of you.

However, the question then becomes does SFML provide the means to perform that checking, to "do everything right"? And in what situations does the language sufficiently provide them?

Take the file example, should SFML provide the means to check if an image file exists? And it's decodable? Well the only good way to check the latter is to decode the image so it can easily be argued a non-decodable image is more or less an exceptional death scenario. But the former part, that a suggested file exists. Is that within SFML's scope? I'm not asking that because I think it isn't, this is more a question to promote discussion since I'm unsure.

And yeah, exceptions are often overused in Java. I can't stand checked exceptions, and the saner usage of exceptions are one of the reasons I much prefer Scala and C# for that kind of development.

As for Nexus' earlier suggestion about dropping C++03 support in SFML 3...yes please? It's been long enough since C++11 went gold. and SFML 2 is very usable by those constrained to C++03. I believe the need for new libraries to support C++03 has passed for the majority of situations (with the exceptions that I would avoid the threading part of the standard when possible until MinGW consistently supports it without needing experimental builds).

And as for following those library design guides, only part I really disagree with is the avoidance of inheritance and virtual functions. That rule is well suited for purely algorithmic libraries and code such as the STL, but I wouldn't say it applies for something such as SFML.

[Hiura]

Maybe SFML should try to adopt some (but not all) of the guidelines at: http://isocpp.org/std/library-design-guidelines

That's an interesting reading, generally speaking – not sure if SFML should follow all the rules there, though.


Re: «one task equal one class» (to sum up extremely quickly the long – yet interesting – discussion above).

MorleyDev, your theoretical point of view is right, I agree. But I also agree with Nexus. Often (if not most of the time) a more practical approach is simpler. Here I think it's the case.

(Extreme) Case study: MVC. Recently I had to port a simulation software written a few years ago that use MVC a lot. My main task was to use SFML instead of a home-made OpenGL wrapper. Well, long story short, even if the code was relatively small (3k loc) I end up removing everything and starting from scratch because it was so complex to reason about the code due to its complex MVC design. I could reduce by a factor of nearly 3 the number of classes, and, more importantly, make it less buggy and more maintainable.

In the case of SFML, splitting the current Image, Sound, ResourceX, ... will introduce bugs (statically speaking, since we would edit a stable code), make it more complex and harder to reason about. So, if a proposed modifications give us more power, flexibility, ... Ok, why not. But currently loadFromMemory is enough for me and can be used to create any fancy facade easily.

I think it's one of those case where the theoretical approach is too academical.

Btw, I read some of the documentation of SFML recently and for some classes you get that long list of methods where only half of them are interesting to most people. There I really wished sometimes it was cut in two parts and I (or the library user just needing a little thing in that diagram) needed to concern myself only with one of those easily understood smaller parts.

Do you have concrete examples? 

[binary1248]

Maybe that would be one of the features that show up in SFML's feature list in the future... After all a Multimedia Library isn't really much if you can't access the filesystem... unless of course you hardcode all your resources into your application, but let's not give people ideas .

SFML already had issues with files not being loaded properly, or STBI causing mysterious crashes when trying to load a directory as an image, so some facility that prevents such things from happening would be a good addition if you ask me.

(Extreme) Case study: MVC. Recently I had to port a simulation software written a few years ago that use MVC a lot. My main task was to use SFML instead of a home-made OpenGL wrapper. Well, long story short, even if the code was relatively small (3k loc) I end up removing everything and starting from scratch because it was so complex to reason about the code due to its complex MVC design. I could reduce by a factor of nearly 3 the number of classes, and, more importantly, make it less buggy and more maintainable.

This sounds like the typical case of people (maybe fresh out of university or whatever) that are over eager to employ what they have learned. What is more important than understanding patterns is how and where to use them effectively. This is also the reason in one of my Software Technology exams we had to argue about why a pattern would be effective in a given sample of code and use case. I guess too many people forget about this too fast .

[Hiura]

@binary1248, well it was an academic project to teach students how to make something – that's maybe why they chose this complex design. 

But that's the actual point. Let's not overthink the design. «Don’t be clever» said Standard Library Guidelines – they also say «don’t be stupid», of course. ;-)

[Ixrec]

Btw, I read some of the documentation of SFML recently and for some classes you get that long list of methods where only half of them are interesting to most people. There I really wished sometimes it was cut in two parts and I (or the library user just needing a little thing in that diagram) needed to concern myself only with one of those easily understood smaller parts.

Personally, I found the small parts/shorter lists were always presented in the tutorials, and I generally check the documentation whenever I wanted to check the exact function signatures/behavior or look up the full range of features the class had.  What classes are you thinking of exactly?

I'm guessing there'd one implementation that outs the error, and one that passes through to that outed error and throws a different exception based on the error? Or the other way around? Actually I'd probably prefer the other way around, it lets SFML at least keep the advantages of exceptions internally even if that doesn't get exposed to the user who doesn't want them.

Either way, it seems like it could be a lot of boilerplate to do that for every function that could throw an exception.

It seems like there should be a way to do this with only one implementation and a few if statements.

void Texture::loadFromFile(std::string filename, sf::Error* e = nullptr) {
...
if(e) {
  e->set("Failed to load " + filename);
  return;
} else {
  throw sf::Error("Failed to load " + filename);
}
...
}
 

Maybe there's a nicer way of passing an error arg with a default that's easy to test against that I'm not thinking of.

Maybe that would be one of the features that show up in SFML's feature list in the future... After all a Multimedia Library isn't really much if you can't access the filesystem... unless of course you hardcode all your resources into your application, but let's not give people ideas .

Since there's going to be a Filesystem standard library in C++14 we probably don't need SFML to implement any of that for us.

[binary1248]

Since there's going to be a Filesystem standard library in C++14 we probably don't need SFML to implement any of that for us.

What is there left to do then? At some point standard C++ libraries will be able to do everything... right?

[Ixrec]

lol, yeah, but I mean that one's already on its way and has a TS submitted and everything; by the time we reimplemented it in SFML everyone would have a C++14 compiler (if we believe Herb's presentations) and our work would be wasted.  We may also get standard 2D graphics and audio libraries eventually but that's much farther down the line, if it's coming at all.

[wintertime]

Btw, I read some of the documentation of SFML recently and for some classes you get that long list of methods where only half of them are interesting to most people. There I really wished sometimes it was cut in two parts and I (or the library user just needing a little thing in that diagram) needed to concern myself only with one of those easily understood smaller parts.

Do you have concrete examples? 

For example I was reading through the documentation of the Drawable hierarchy and its maybe just a documentation thing and not a problem with the classes, but I was trying to find whats different and whats common and there some annotations in the short list for new methods, overwritten and slightly different, overwritten just to adapt to the underlying data but doing exactly the same and unchanged methods would have helped. Also the pages got a bit long with having to scroll up and down so splitting them in two may be helpful, maybe such that one could have a page with only the differences to the base class. Compared to other libraries SFML docs are nice already, but some improvements can always be had.
Then like was discussed above all those different create and load functions clutter up the resource classes, when there could be just 2 or 3 contructors mostly and people could just use a single generic Load for all of them and Decode could also be split off, though I see how that could disrupt current users a bit.

[Ixrec]

Honestly the function lists for Texture and Shape (since Drawable was trivial) don't look that long to me.  I barely have to scroll at all unless I want to go down to the detailed descriptions, and for some reason don't like clicking on the function's name in that list.  It might be hard to keep every single one of the functions in your head, but for those classes at least there are a lot of obvious groups that it's hardly overwhelming imo.  Plus there's a tutorial specifically on drawables, so if you read that first the hierarchy ought to make a lot of sense.

Though I notice the position/rotation/scale/origin functions are all duplicated in Shape/Sprite/Text but not in VertexArray, and until you look around for a minute it's not obvious that Shape/Sprite/Text all inherit from Transformable, so *maybe* an improvement could be made there.  I'm not sure quite what it would be though.

[Nexus]

Maybe that would be one of the features that show up in SFML's feature list in the future... After all a Multimedia Library isn't really much if you can't access the filesystem... unless of course you hardcode all your resources into your application, but let's not give people ideas .

How would SFML benefit from a filesystem library? Only by making error messages a bit nicer?

I believe the other cases that are typical for games, such as archives, file dialogs, ... are too high-level for SFML anyway. There exist already portable and well-tested libraries such as Boost.Filesystem (and C++14 in the future), I don't think it makes sense to reinvent the wheel once more.

Also the pages got a bit long with having to scroll up and down so splitting them in two may be helpful, maybe such that one could have a page with only the differences to the base class. Compared to other libraries SFML docs are nice already, but some improvements can always be had.

Luxury problems...

The documentation is limited by Doxygen. Considering its internal mess (I've had to modify the source code in several places), we can be happy it works so well I like the SFML documentation; it's really well done, you don't find that a lot for C++ libraries. And we should probably not design the API only for the sake of appearing nicer in the docs

[Ixrec]

Come to think of it, I've heard people say/imply in multiple places that Doxygen docs are bad, but to be honest I've never seen good documentation that didn't use it (SFML's tutorials/docs are the clear gold standard out of everything I've read), and I've never seen anyone suggest an alternative.  Of course good tutorials always have to be done by hand but they're a lot harder to screw up than comprehensive documentation.  So are there alternatives?