What do you like in your libraries

Member
Posts: 72
Joined: 2006.10
Post: #1
I am about to release (unleash?) a few of my personal libraries to the world at large. The selection will mostly be based on my personal level of satisfaction of the library I consider releasing (thus forcing me to cleanup my code, which is the main point of this exercise). I do not necessarily expect my libraries to be used in actual products anytime soon, but I would still like them to be in a shape that can be deemed "professional".

Before anything else, a bit of context. The set of libraries in question is pure C++, with fully dOxygen marked-up headers, buildable as either static libraries or embeddable frameworks. The structure is meant to be platform independent, but some libraries might get released before that criteria is met. The whole set is aimed directly towards MAC game development, but is generic enough for other tasks.

Before I publish anything out there, I would like to query you guys about a few points that are still up in the air:

1. STL: how much do you hate them? I make extensive use of STL at this point. strings, lists, maps, hashmaps (extended stl) and the occasional vector where appropriate are all over the place for convenience reasons. Would that turn you off to the point of not using a library altogether? I just don't feel like writing a string class if I don't have to. The same goes for other data structures, STL does an awesome job by itself. However, if people would go up in arms about it, I'll bite the bullet.

2. Memory allocation: micromanagement fan? How fine grained do you want control over memory allocations?

3. Exceptions, want them? I do not throw any exceptions, error management is done through returned values, are you fine with that?

4. Namespaces, enough said. Every library currently has its own namespace, and it can get... messy... here are a few samples:
Code:
ObjectLib::StrongPtr< SceneLib::Camera > mCurrentCamera ;
  mCurrentCamera.instantiate() ;
  mCurrentCamera->setPosition( MathsLib::Vector3D<float>( 0.1f , 0.3f , 10.0f ) ) ;
The "using namespace" syntax is always there for you anyways, are you cool with that?

5. Templates, scary enough? As you can see in the previous code sample, templates are used extensively. To give you an idea on the meaning of "extensively", here's a choice sample from the MathsLib:
Code:
template < class T , unsigned int n , unsigned int m >
class StaticMatrix : public StaticVector< StaticVector< T , n > , m >
{
...
} ;
Which is a lot of awesome because it auto-magically implements the matrix[i][j] syntax amongst other things. However, some people have serious objections against templates. Are you one of them?
In all honesty, I can't really change that, so if you tell me that you have a problem with it, I will only be able to shrug and say: "your loss", but I still value your opinion on the matter.

And finally, anything other comment that springs to your mind is also greatly valued.

Thank you very much for your input!

--
Sohta
Quote this message in a reply
Luminary
Posts: 5,143
Joined: 2002.04
Post: #2
Personally, "C++" is probably enough to turn me off your libraries, unless they do something much better than any alternatives. That said...

1) It's the standard library... objection seems futile. Much better that you use the std::string class than write your own mess.

2) If you're trying to be portable to Windows, giving the user control over memory allocation might be important. The rest of the time, unless there's a very good efficiency reason to do so (eg. std::list), don't.

3) Absolutely not. Exceptions are evil, especially in C++.

4) Namespaces are better than none. If you don't want to see 'em, you can always "using namespace" and they're gone. Absolutely no reason not to use 'em.

5) Templates where appropriate are fine.
Quote this message in a reply
Member
Posts: 72
Joined: 2006.10
Post: #3
OneSadCookie Wrote:Personally, "C++" is probably enough to turn me off your libraries.

Yeah, I'm actually with you there. As I said before, this is more about me then anything else. My job involves a LOT of C++ programming (I would like to change that, but it won't happen anytime soon, trust me). It's really important for me to polish my "trade" as much as possible, and generic library development is just an outlet for that. Making C++ tidy and usable is one of my main goals with this.

OneSadCookie Wrote:unless they do something much better than any alternatives.
Some of the things in there are actually rather nice. I'll get into the details later.
Quote this message in a reply
Sage
Posts: 1,199
Joined: 2004.10
Post: #4
I'm with you on everything, though I think templating for templating's sake can be more trouble than it's worth. I certainly do use templates, but your StaticMatrix example seems like it would result in a pretty high learning curve for a new user.

Also, regarding namespaces, for my own work I try to keep my namespace names short and to the point so as to not coerce myself into a lot of 'using namespace foo' statements. For example, my user interface code is all in the namespace 'ui' in the namespace 'sgf' ( for simple game framework ).

Also, the STL's great. I have no interest in writing my own set<>, map<>, etc. Iterators are great, too. No reason to feel bad about using a great bit of well designed plumbing.

That being said, I'd like to see your library. I'd probably learn something from your template work.
Quote this message in a reply
Member
Posts: 72
Joined: 2006.10
Post: #5
TomorrowPlusX Wrote:but your StaticMatrix example seems like it would result in a pretty high learning curve for a new user.

it depends a lot, for example, I also have this class:

Code:
class AffineTransform : public MathsLib::StaticMatrix< float , 4 , 4 >
{
...
};

which means the user can write stuff like:

Code:
AffineTransform a ;
  AffineTransform b ;
  
  a.setTranslation( Vector3D<float>( 0.0f , 0.0f , 20.0f ) ) ;

  b.grabFromGLModelviewMatrix() ;
  b *= a ;
  b[1][1] = 2.0f ;
  etc...

The templates are completely hidden from the user!
Quote this message in a reply
Moderator
Posts: 370
Joined: 2006.08
Post: #6
Personally, I've never been a big fan of the STL, but that's mainly because people abuse it so awfully. If you're libraries make good, efficient use of the STL, I'd have no complaints
Templating is fine with me.
I'd much rather have functions return error values than throw exceptions; I'm also a big fan of OpenGL's way of handling errors, by setting a global error value and then letting you query it any time you want Smile
-wyrmmage

Worlds at War (Current Project) - http://www.awkward-games.com/forum/
Quote this message in a reply
Luminary
Posts: 5,143
Joined: 2002.04
Post: #7
wyrmmage Wrote:I'm also a big fan of OpenGL's way of handling errors, by setting a global error value and then letting you query it any time you want Smile

Another truly atrocious idea. The number of posts to the mac-opengl list which are people not remembering to check glGetError is too large.

I think checked exceptions are the right way to do this kind of thing, but unfortunately other people don't seem to feel this way, and I'm only aware of Java that has them, and even it has a half-assed implementation.
Quote this message in a reply
pointer
Unregistered
 
Post: #8
Wow, am I the only one who likes C++ here? Cool

sohta Wrote:1. STL: how much do you hate them?

Not at all, it's fine as long as you know what you're doing. I use it myself.

Quote:2. Memory allocation: micromanagement fan? How fine grained do you want control over memory allocations?

Pretty fine grained where performance is crucial, like resource handling (model data in VRAM, etc), managing objects, utilizing caches, etc.
One thing to think about (especially if you want to support video game consoles) is to be able to stream all the resource data directly from disk into memory instead of reading one file, parsing it, then reading another.

Quote:3. Exceptions, want them? I do not throw any exceptions, error management is done through returned values, are you fine with that?

I like exceptions, they work great with RAII, they free up the return value from functions and I think they're the way to go in C++. Mind you, you shouldn't throw exceptions all over the place.

Quote:4. Namespaces, enough said. Every library currently has its own namespace, and it can get... messy... here are a few samples:

Sure, but I tend not to use "using", so I prefer shorter names.

Quote:5. Templates, scary enough? As you can see in the previous code sample, templates are used extensively. To give you an idea on the meaning of "extensively", here's a choice sample from the MathsLib:

Templates are fine; but don't use them just because they're cool. I'd probably say your StaticMatrix is a bit like that, but what does it matter if the user isn't going to notice and it's clear enough to the maintainer Ninja
I rarely use templates for that kind of stuff, my vector classes are defined to use a typedefed primitive to store the values, so are my matrices. But that's probably because I don't like having code in my header files Smile

Just my ¢2, hope I won't get bashed too much Sneaky
Quote this message in a reply
Member
Posts: 72
Joined: 2006.10
Post: #9
Thank you very much for all your replies!

A few clarifications are in order:

Short namespace names: A huge no-no for public-release libraries, it's just asking for conflicts in the long run. This could be solved with a meta-namespace, but I really don't like that.

Excessive templating:
I chose StaticMatrix as an example because it's my worst case, yet one that actually has a big impact for me since I personally use matrices for a lot of things. The main culprit here is neural nets. Having statically allocated 10*4 , 4*5 , 5*2 matrices without having to write any code to make it happen will make your MLP code much more efficient and maintainable (as long as they behave nicely for Matrix-Vector multiplications, which they do). Anyways, they are constrained to the ultra-low level libraries. You won't find any template declaration in the renderLib, that's for sure.
Quote this message in a reply
Sage
Posts: 1,199
Joined: 2004.10
Post: #10
pointer Wrote:Wow, am I the only one who likes C++ here? Cool

I love C++. But, I also love python, ObjectiveC, C...

Don't feel discouraged. iDevGames is full of people who hate -- HATE C++. They have their reasons, and that's cool. But there's plenty of people here who quietly use C++ and keep it more or less to themselves so they don't get yelled at.

As an example, I've released some simple enough ( C++ ) code here and there on this forum. Threaded capture-to-quicktime code, font loading, etc. In each case, people took my code and rewrote it in ObjC, even though it did work in C++.

But, that's cool. I'm happy to have provided a jumping off point for them. Also, the ObjC version of my quicktime recorder seems better...LOL
Quote this message in a reply
Moderator
Posts: 623
Joined: 2007.09
Post: #11
I both love and hate C++. unfortunately, I've never used it. But it does have a cool cin/cout function…Rasp
Quote this message in a reply
Luminary
Posts: 5,143
Joined: 2002.04
Post: #12
Hairball183 Wrote:I both love and hate C++. unfortunately, I've never used it. But it does have a cool cin/cout function…Rasp

Shock Sad Annoyed LOL Rolleyes Blink Cry Huh Wacko
Quote this message in a reply
Moderator
Posts: 608
Joined: 2002.04
Post: #13
Hairball183 Wrote:I both love and hate C++.
Probably not the best judge then...
Quote this message in a reply
Member
Posts: 24
Joined: 2008.01
Post: #14
OneSadCookie Wrote:3) Absolutely not. Exceptions are evil, especially in C++.

What's wrong with exceptions? They're one of the best features of C++ and, when employed correctly, can lead to very clean code and easy maintenance.

Unfortunatly, most people don't know how to use them correctly, and just slag off the entire concept as evil. I suppose the same could be said for the entire C++ langauge and the STL Blink

@sohta

Looks very cool. The great thing about C++ is that you can hide the details if you want to; namespaces can be cancelled out with 'using', type declarations can be wrapped in typedefs, and operators can be overloaded. If it provides the required function, I really don't think people will be too hesitant to use it. Just because you use the STL or std::string doesn't mean they have to.

I know there are some libraries that pander a little too much to 'purists'; take TinyXML for example, an excellent XML library which defines switches for turning off STL and exceptions. I think you're just making more work for yourself. Go ahead and release it Rasp

Oh and (a little thing), it's 'Mac' not MAC...
Quote this message in a reply
Luminary
Posts: 5,143
Joined: 2002.04
Post: #15
Danny77uk Wrote:What's wrong with exceptions? They're one of the best features of C++ and, when employed correctly, can lead to very clean code and easy maintenance.

It's about code correctness. Exceptions hide control flow, and in fact, allow alteration of the implementation of functions you call to change your control flow in unanticipated ways.

Basically, if any function in your app can throw an exception, *every* function in your app must be coded in such a way that *any* exception thrown from *any* function it calls produces a correct result. This is not an easy thing to do, and not an easy thing to test.

C++ fanatics might get a kick out of writing RAAI wrapper classes for fopen/fclose, glPushMatrix/glPopMatrix, glBegin/glEnd, new/delete and every other matched pair in order to make their code exception-safe, and introducing a million new scopes to get destructors called at appropriate times, but it doesn't appeal to me.

Java more or less gets this right. The most common "matched pair" in C++ is new/delete, and it's not a matched pair in Java due to garbage collection. Most exceptions in Java are used to indicate logic errors, and are not expected to be caught. Those that are expected to be caught, the language forces calling code to be written in such a way that the exception is handled (either by explicitly declaring that it's not caught, or by catching and handling it). For the matched pairs other than new/delete, Java provides "finally", meaning you don't have to create a million wrapper classes.

Bottom line: with C++ exceptions, code might *look* clean, being in a straight line, but its control flow is probably spaghetti, unintelligible, and hiding hundreds of latent bugs. Maintenance is an absolute nightmare, because whenever you introduce a throw statement, you have to examine every function that could appear in the call chain above this one and check it copes with the new exception.

Quote:Unfortunatly, most people don't know how to use them correctly, and just slag off the entire concept as evil. I suppose the same could be said for the entire C++ langauge and the STL Blink

I do know how to use them correctly, and I believe that it is possible for exceptions to not be evil (c.f. Java's checked exceptions). My distaste for unchecked exceptions stems from years of experience of their horrors in C++, Java, Ruby, etc. My distaste for C++ stems from years of experience with C++ itself, and the alternatives. See OneSadCookie: Why not C++?. There are other reasons to dislike C++ too, such as speed of compilation, size of compiled code, and sheer impossibility of understanding the language, but I think they pale in comparison.
Quote this message in a reply
Post Reply