Reading Programming

My most recent project makes use of SDL Library(Simple DirectMedia Layer). I reached a point in the project where I needed to add a simple gui interface that could run atop SDL. I experimented with several libraries and my experiences have driven me to the melting point where I am forced to rant about poorly designed and poorly implemented libraries inspired me to write this set of guidlines for the friendly coder.

Unnecessarily reinventing the wheel is perhaps the worst sin of programming. It's something we all avoid. To help avoid this, almost all programming languages (Note: In the context of this guideline, examples will be based on Java and C++) provide some method of distributing reusable code through libraries, modules, or some other mechanism. Most programmers understand how to create and distribute reusable code but many times, the distributed package may be intrusive and messy. We will refer to this as rude code.

How does one avoid distributing rude code in a library?

1. The design of the code should be intuitive and relatively straight forward. When programming, one may create functions or methods with names that have no meaning to outside developers (For example: pset, mDL, mUL). When creating a project for distribution, this should be avoided. If you're planning to distribute the actual source code, then you should add comments (I should but I don't). I won't go much into this as this depends on individual scenarios.

2. Avoid intrusive code. Hopefully, you are asking "what's intrusive code?". Intrusive code is code which controls too much of an application making it hard to integrate into an existing application.

Example: A developer has already created an application frame work and wants to add a special feature very late in the game. The library providing the special feature the developer wants to use automatically creates its own generic application framework.

This is what I would call rude code. While it may be helpful to someone that needs to quickly create an application framework, it becomes a setback to the developer with an existing customized framework. The developer may be forced to commit the sin of reinventing the wheel!

3. A second type of intrustion. Though this form of intrustion is not as bad as the first, it may result in a messy or oversized distribution. This form of intrusion involves libraries which require multiple files or a very large file at runtime. The violation occurs when the distribution of the oriignal program becomes excessively bulky.

Example: To provide a small feature, a developer uses a library which requires multiple DLL files. The new distribution is several times larger than the previous distribution.

4. Make code as flexible as possible. You want your code to be simple enough for novices and powerful enough for professionals. If you're going include convenience functions which make things cleaner or easier, provide ways to override these functions and allow access to the underlying mechanisms. If wrapper libraries are intended for advanced developers, they should not completely obscure the functions of the original library.

5. Make the integration of code into existing projects as easy as possible.

I hope that was helpful.