Once Again, Most Documentation Sucks

I have been having fun, recently, programming a couple of services that run in Google’s App Engine. One thing they do is maintain some data in that cloud’s version of a database, so one of the important aspects of the services is controlling just who, exactly, is allowed to see or modify the data. I’ve actually got a solution in place that means it all works just fine for me.

My wife has pointed out that if I’m solving an actual problem that I have, then it’s likely that there are other humans who have the same problem and who might benefit from being able to use my solution. This seemed completely reasonable and so last night I started sketching out how to modify one of the services so it would support multiple users. Today, I started making filling in the sketch and doing some basic refactoring so that would work. And then, half an hour ago, I made a big mistake.

I thought, “Well, this solution works for me, but that’s because I can make a bunch of simplifying assumptions based on my specific case. How can I open this up a bit more?” and then I started reading up on pac4j, which led quickly to buji-pac4j, which got me to Gradle, and the next thing I knew I stopped enjoying what I was doing.

This seems to be something that happens pretty often with me. I start reading up on a framework or tool chain, fool around with it and get to understanding it, read up a bit more, and then pretty quickly I get to a point where I’m considering some library where the author’s approach seems to be, “This is a flexible and powerful tool; everyone should use it! But it was ever so hard to write it so I don’t see why I should make it easy for anyone to use it!”

So, an hour later, I’m back at my own existing code and I think I’m just gonna keep a bunch of my simplifying assumptions. Yes, that will reduce the potential user base of my code pretty dramatically, but I don’t have to give myself a headache trying to figure out how to get this poorly-documented library to interact with this other undocumented service all so that my code can figure out if the current web request should be allowed or not.

Published by pirateguillermo

I play the bagpipes. I program computers. I support my family in their various endeavors, and I enjoy my wonderful life.

Leave a Reply