Design Limbo

I recently stumbled on a Java/.Net open source project called BouncyCastle when I was running into issues using Microsoft’s implementations of RSA in the .Net Framework. I thought to myself, “Open source to the rescue again!”, Boy was I wrong. Let me go on records as saying it’s a good project and has a ton of useful API’s in it, the problem there is no documentation or examples.

There are a lot of open source frameworks out there. But there are very little that are truly great. I believe this is because people are so into the code and the architecture that they forget that there may be other people using the framework. This is why, documentation is king of your project!

If you are publishing a framework for other people to use without any kind of documentation you really have failed. Even the smallest of frameworks should have a little bit of documentation. Frameworks especially should have well documented samples. If your potential user is browsing your unit tests trying to figure out how things works, there is a problem.

Here is a checklist that I think is a must have for any framework:

1. Easily to navigate website (i.e. CommunityServer/Wiki)
2. HTML documentation on the site
3. CHM or VSDoc with the download package
4. Samples of the 80% (common) scenarios with the download package
5. Forums or other web community system (not a mailing list!)

There is an old adage when it comes to documentation and is goes something like this; “Outdated documentation is worse then no documentation”. That is a bald face lie put out by people who would prefer to never write documentation. Old documentation can be really confusing and frustration but what it does provide is a sign that could point someone in the general direction.

At the time of this writing I’m trying to figure out why BouncyCastle’s RSA implementation just spit out garbage to me. Was it padding? Did my encoding not work right? Was I calling the correct thing? I don’t know and because there are no samples or any documentation to speak of trying to orient myself in the right direction is a difficult task. Frameworks are supposed to make developers lives easer by making complex tasks simple, but without a solid foundation of documentation, samples and community it only adds more work.

On Friday a blog post from Joel Spolsky hit Slashdot. This post from Joel was a good read and centered around using programmers who, “Just get the job done”, or as Joel referred to them as Duct Tape Programmers. The gist of the post centered around not worrying about n layers of abstraction to complete a simple task, but to code it and ship it. It’s a good read and I recommend it. Uncle Bob also posted a rebuttal, which is a good read as well.

I like the feeling behind Joel’s post and I probably would consider myself a Duct Tape Programmer, but I don’t think I’m good looking enough. But I think Joel is just a little left of center with his post and it misses the mark on what we should be communicating to our fellow developers. I believe the message to developers should be that of moderation and not out right not doing.

Is an application with three layers of abstraction better then an application with none? Can you honestly answer that question? Does loosely coupling your application make it better then one that is tightly coupled? If you answered yes to that then your missing the whole point of software development. Software development is an art form and the patterns and practices that we employ in our field don’t always apply to every software application we build. Every piece of software we code is in a vacuum, and we need to apply the best tools for the job to complete the job well.

What I got out of Uncle Bob’s article is that I can develop bad applications without ‘complex’ tools like multi-threading and abstraction just as easily as I can with them. Just because I have to tool in my toolbox doesn’t make me included to use it, and we should be forced to. I’ve build some small tightly coupled applications that work great and haven’t failed or stopped working in years, does that make them bad?

There are some universal truths in our field though. I’m not a huge Unit Testing fan and I think people can go way overboard with it. But having some unit tests that exercise your code business logic is never a bad thing. But in crunch time will I cut unit tests or functionality? Probably unit tests, sorry boys and girls but unit tests aren’t a deliverable the vast majority of the time. But does that mean it’s ok never to do them just because they may be the first to be cut? No, never, never. I’m not a fan of TDD but it can be extremely useful and it just another tool in the box, like paired development.

I don’t think Joel is calling all non Duct Tape Developers stupid, but I think entering into a project with a rigid set of tools and patterns is, and so is the reverse. Don’t empty your tool box because you don’t like TDD or Unit Tests, but try to use them from time to time. Also don’t try and apply TDD and 100% code covered to an application that just emits “Hello World” to the console. Yes a lame example I know.

If you never try those things how will you know if they work? If you never try multi-threading and application or writing a few layers of abstraction can you expect to correctly identify where they will come in useful and how they will be useful? If you never tried TDD can you determine where and why it’s useful? Fill your toolbox with great tools, like Duct Table, but always remember to draw up a blue print to use them correctly.

“Memento Audere Semper” Remember Always to Dare.

I worked with a guy who would say “With a K” to imply something is not the real thing. For example instead of calling foe pearls that, he would say “Those are pearls with a K”. It’s not something I ever picked up and ran with but hey, to each his own. My target of rage as of late has been the RSA implementation that ships in the .Net Framework.

The underlying mathematics of asymmetric encryption allows for encryption and decryption from either key. So I can encrypt data with my private key and only the public key can decrypt it. I can also encrypt data with my public key and only the private key can decrypt it.

The mathematics underlying the algorithm provide for this functionality, but it’s not in the .Net Framework. The implementation that is currently in the .Net Framework is a broken, one way (Public->Private), implementation.

This implementation works good for the common scenario where I have a public key I can give away over the Internet, people can encrypt data and only I can decrypt it. What this doesn’t provide for is you communicating by encrypting with your private key and having your public key decrypt the data.

The common rational I see popping up, is that because the RSA is a CPU intensive process that it shouldn’t be used to encrypt anything more then a small amount of data, say a symmetric encryption key. I would agree with this but crippling the entire implementation in the .Net Framework and not having a more ‘advanced’ option is very limiting.

The scenario I recently wanted to use the asymmetric encryption, and the RSACryptoServiceProvider, for was to one time encrypt information and many time decrypt. A system would generate some data that could only be read, so using the properties of asymmetric encryption, I could just encrypt with my private key and publish my public key embedded with the software. This way the secure data could only be decrypted with the public key and not modified. This is all the benefits of symmetric encryption coupled with hashing, all in one operation.

I now use Chilkat Software’s working RSA implementation to accomplish this goal and only recently stumbled across a open source encryption library called Bouncy Castle (yes I know the name sounds weird). To me the .Net Framework is very “Pit of Success’ie"” but doesn’t provide any flexibility for other use cases, for something that should be available in the base framework. Yes asymmetric encryption can be computationally expensive, but that is not a reason not to support the 20% or more advanced scenarios.