My complaints on bullet's source code quality

[godlike]

First of all I have to say that I am using bullet, I love bullet, I am grateful that we have bullet. Please excuse me for the following complaints but after seeing bullet3 source code and no real improvement on the source quality I feel the need to write a few things.

First the minor:
- Lines that span to infinity.
- When it's time for newline sometimes is 1, 2 or 3 newlines. It seems random.
- Tabs to align things (eg SIMD_FORCE_INLINE<tab>int size() const). This looks ugly and sometimes it is used, other times not.
- Why should I include the path of bullet header files in order to use it (g++ -I /path/to/bullet_headers)? This is because bullet internally includes the header files like this: #include "BulletCollision/NarrowPhaseCollision/btDiscreteCollisionDetectorInterface.h". No other library does that. What others do is to install all headers inside /usr/include/bullet and internally include like this: #include "bullet/BulletCollision/NarrowPhaseCollision/btDiscreteCollisionDetectorInterface.h".
- Every file has the "bt" prefix. If the files are placed as mentioned before there is no need for that.

And the more serious:
- Defines that don't have BT_ prefix (eg USE_OVERLAP_TEST_ON_REMOVES)
- Not many comments to explain the source code.
- No proper doxygen comments on header files.
- Poor documentation. Being under-documented is often mentioned but not improved.
- What's wrong with having a nice "bt" namespace instead of prefixes?
- Inconsistent code style (eg void func()\n{ and void func2() {\n).

As I said before I don't want to sound ungrateful and I don't believe I am better than the people that contribute to bullet. With all the love and admiration I have and after seeing numerous codebases over the years I feel that bullet needs improvement.

Also, I am willing to write a code style document and refactor as much code as I can if someone asks.

[emersonmx]

The Bullet documentation is virtually non-existent for certain things. And when you need to do something that is not in the documentation you will only have two options. This forum and the the source code (demos and API). When there's no one to answer your questions in the forum, the code is the only option, but when you look at the code you end up rooting for someone to help you.

I also have some complaints about the library, you quoted some and not others, but I think that my complaints can be summarized as follows: The Bullet is a physics simulation library written in C and C++. I never liked to mix C and C++, because it leaves the code functionally messy. I really do not think that using callback functions is a C++ approach, or use the prefix bt instead of a namespace.
It would be a really good write up a code style document and refactor (even if it will break the API).

In the end this will only help make it easier to maintain and use.

----
The Google Translate was used to write this post, so there may be inconsistency xD

[Mako_energy02]

I agree on all points, as I think most of the people in this forum do. The problem is that Erwin seems to be the only person actually managing the library and his focus seems to jump around in ways I don't really understand. Although I know his focus right now is on Bullet3 and getting the GPU pipeline up and running.

For anything else we as the community are expected to provide for those things(such as a good and working Kinematic Character Controller /shakefist). To an extent that is ok. The problem with this is 2 fold:

1) The sheer lack of documentation ensures that anyone that sticks with the library long enough to become a guru with it, really is only a guru in the capacity they used it in. Sure we can test and tinker with the demos and gleam things from the forums, but without actually understanding edge cases and intended uses we really can't become actual "experts" to the same capacity Erwin is. Thus most posts on this forum go unaddressed. Better documentation -> More Experts -> Better Community.

2) The management of the issue tracker is suboptimal. Most patches in the issue tracker lie there for a while with little to no feedback. Some lie dormant for quite a while. It hasn't stopped me yet, but I do hesitate to submit patches to Bullet for these reasons.

But again, Erwin is just one person. Bullet needs more people (at least more publicly facing people like Erwin) to really get to where the community wants it to be. Then these other issues can be resolved one at a time.

[godlike]

One problem of under-documentation, as mentioned in the previous post, is ofcource the difficulty we face when we want to use bullet. Another serious issue is the fact that it's difficult for someone to contribute. There were a few occasions where I wanted to fix a bug or investigate something but after trying to understand the code I lost my patience and gave up.

Bullet3 is under development and it's not too late to do some things differently.

[Erwin Coumans]

Thanks for the feedback.
Remember that there is no team working on Bullet, it is just me and some occasional external contributors that come and go.

My focus for the last few years has been to get a rigid body simulator working on GPU, in the Bullet 3 project, using OpenCL.
Applying patches and improvements to Bullet 2.x was not a priority, due to time constraints.

Bullet 3.x is the main repository and all Bullet 2.x features will need to migrate (I plan on closing/freezing the googlecode repository).
So the new Bullet URL and issue tracker is now at http://github.com/erwincoumans/bullet3

I choose for the B3/bt prefix and there will be no namespaces in Bullet, and I am happy with that. There should be no issue with that.
I will look into adding more comments and better documentation in 2014, in addition to merging all Bullet 2 functionality.
You can help with this: tell in details what feature/class/method you want to see documented?
Be specific: instead of "all classes of Bullet", list some methods/things that you want to see documented first.

Thanks and happy new year,
Erwin

[Mako_energy02]

You can help with this: tell in details what feature/class/method you want to see documented?
Be specific: instead of "all classes of Bullet", list some methods/things that you want to see documented first.

My vote would be to start with the btSliderConstraint. In the demos you don't have an example using it, instead opting for using a Generic6DofConstraint configured to act like a slider. Is the btSliderConstraint no longer intended for use? If it is not deprecated, what are the effects of configuring Softness, Restitution, and Damping? I assume "Lin" and Ang" in the function names means Linear and Angular, but what does Lim mean? I also believe Ortho means Orthogonal, but in the context of constraints that means very little to me. What range of use cases was the btSliderConstraint intended to simulate(beyond a forklift)?

[Flix]

My vote would be to start with the btSliderConstraint. In the demos you don't have an example using it [...]

Just to say that there is a demo using it: it's the SliderConstraintDemo.

[c6burns]

Just my own 2 cents, I'd rather see Erwin continue to work on code ... features, bugs, etc. Documentation is less important to me than code. I haven't had any questions yet that 20 minutes of digging through the code didn't answer. The demos are also a great starting point for any implementations.

With open source projects I'm used to the developers just focusing on code and the community maintaining documentation. Erwin is plenty active enough on the forum to answer questions that come up for documentation.

Sure having the entire code base doxygen'd would be nice, but I certainly don't want that instead of new features or waiting for bugfixes. The namespace honestly who cares ... maybe that's the C coder in me talking. To me this thread should be a volunteer thread instead of a list your problems with bullet thread. If you are unhappy with documentation, then consider putting some of your own time into improving it? Being the "idea man" who came up with the idea to improve the documentation isn't worth much when you think about it.

[Mako_energy02]

My vote would be to start with the btSliderConstraint. In the demos you don't have an example using it [...]

Just to say that there is a demo using it: it's the SliderConstraintDemo.

That is counter-intuitive and I am embarrassed. It should be with the other constraints, in my opinion.

I retract my statement regarding the lack of a demo, but I would still be interested in more explanation like I stated in my previous post. Thanks.

Just my own 2 cents, I'd rather see Erwin continue to work on code ... features, bugs, etc. Documentation is less important to me than code. I haven't had any questions yet that 20 minutes of digging through the code didn't answer. The demos are also a great starting point for any implementations.

With open source projects I'm used to the developers just focusing on code and the community maintaining documentation. Erwin is plenty active enough on the forum to answer questions that come up for documentation.

Sure having the entire code base doxygen'd would be nice, but I certainly don't want that instead of new features or waiting for bugfixes. The namespace honestly who cares ... maybe that's the C coder in me talking. To me this thread should be a volunteer thread instead of a list your problems with bullet thread. If you are unhappy with documentation, then consider putting some of your own time into improving it? Being the "idea man" who came up with the idea to improve the documentation isn't worth much when you think about it.

I disagree with just about everything here. Only exception being that yes...I believe that is the C coder in you.

The demos aren't adequate, not on their own at least. I have also source dived to get answers to how various things work, but I really, really should have to look around the guts of bullet that much to understand what I need to do. Your lack of questions doesn't really seem like praise for Bullet to me, rather it sounds like you haven't really tested Bullets capabilities yet.

When it comes to documentation, it really doesn't slow you down by much. Yes it is more work and that is more time, however you can create and document your API as you build the model of what you are creating in your head, then make the implementation. When you do it right, it's very little extra time. So it's not a "I can do this, or this" type of thing at all.

Expecting community based documentation only really works when there is a certain minimum of documentation already available, or if the API is just intuitive enough to not need it(almost never the case in my experience, and certainly not the case here). People need to be comfortable with the limits of the software and then they can tinker and report back with bug fixes, edge cases, and cool implementations more comfortably. No one here is trying to get praise for being an "idea man". I honestly have no idea where you got that idea and seems like you are getting needlessly adversarial with that comment. We just want a slight bit more effort on the part of the Authors to make our jobs easier...and it will generate returns in the Bullet community.

[c6burns]

When it comes to documentation, it really doesn't slow you down by much.

I don't think this blanket statement fits every situation. It depends on the project and the coders and etc. I've spent considerable amounts of time on documentation for several open source projects ... it can be an exhausting amount of work depending on the level of existing docu. It can definitely become a this-or-that activity ... create features/fix bugs or write docu and you have to choose between. I appreciate the point you are trying to make about doing it as you go, or having it be part of the code process, but I don't think that's the situation this library is in right now. It has almost nothing and needs everything ... it's a do this or do that issue.

Expecting community based documentation only really works when there is a certain minimum of documentation already available, or if the API is just intuitive enough to not need it(almost never the case in my experience, and certainly not the case here). People need to be comfortable with the limits of the software and then they can tinker and report back with bug fixes, edge cases, and cool implementations more comfortably. No one here is trying to get praise for being an "idea man". I honestly have no idea where you got that idea and seems like you are getting needlessly adversarial with that comment. We just want a slight bit more effort on the part of the Authors to make our jobs easier...and it will generate returns in the Bullet community.

Yes I should have been more careful how I worded that. I didn't mean it to come off like I was calling anyone out, but then again who among bullet users doesn't realize that documentation can be improved? The idea on its own doesn't get us anywhere is my point. Someone still has to actually go write the docu, right? I'd prefer if it wasn't the core team (aka Erwin) that has to do it, though my preference may be the absolute minority. Also we clearly have different expectations from an MIT licensed project. You don't expect to have to look inside the source to understand how things work, and I do. An open source project with the level of docu that (for example) Ogre has is an exceptionally rare gem in my experience. Getting there for bullet will take a serious amount of effort, in my opinion ... it's a community issue and not an issue just for Erwin.

[billias13]

Bullet is a huge library to be supported by just one person. Erwin has done an amazing job in open-sourcing, maintaining and improving this library, and
since a large number of people worldwide are using it, this community should become more involved and actually contribute rather than requesting. This
is how large scale open-source projects work in general.

I think that most of us using bullet, don't actually know how it works, and indeed the reason is the lack of documentation and poor source commenting. I am afraid
that due to the increased complexity of version 3 (OpenCL is quite complex sourcewise) this effect will only get worse. So, since version 3 is not the main version yet,
there are steps that could help :

1. A standard coding style could be decided by Erwin, and i am sure that a lot of people would be able to spare some time and change the existing code using this style.

2. A few comments and an abstract documentation regarding the actual techniques applied (publications, algorithms etc) would help users to understand what each source file is doing, and hence allow them to involve more actively. Erwin is not obliged to do everything on his own, its practically impossible, but he is the only one that that can provide necessary info so that other people can grasp on that and contribute on writing a decent documentation, improving doxygen etc.

I know that the main focus is on version 3, but i believe that even then, most of the users will still continue with version 2 for basic stuff, since most of them require simple stuff such as few rigid bodies, small scale worlds etc, and version 2 provides them in a very easy way to implement.

(Excuse my poor English)

[xexuxjy]

Having ported bullet to native c#/xna I've had to become very familiar with a lot of the source code. It's very obvious that certain sections have been cobbled together from existing code libraries (even things like the use of different row order,column order matrices in different parts of the system). I think that most of this comes from the fact that people use the standard bullet distribution as a 'starting point' and then produce some very heavily customised versions that are better for their specific problems (particularly on the gamedev side). Some of these customisations make it back to the main branch, (SPU , SSE instructions and so on) , but as they are very very specific they tend to make understanding whats going on quite a task.

It also means that people wanting a simple introduction to Bullet can struggle quite a bit, the demos are an excellent starting point but it would be good to see some larger examples of games,apps, whatever using Bullet to get a better feel for how things work

Erwin has done a very good job of adding in fixes and features on new versions, but as he's only one person there isn't much opportunity to make 'cosmetic' code or structure changes, particularly as things 'work' as is and regression testing all this could be a lot of work. From what I've seen of the Bullet3 source code it's a fair bit cleaner, and that may be a better place to focus future efforts on.