Skip navigation

Tag Archives: kids always document your code

Back in the day, I was really eager to work with anything you can slap an acronym on. Practice on MVCs, JDBCs, and APIs was sorely lacking in Computer Science at any level, I’d wager, but even more so in undergrad. Heck, How to Design Programs even tiered Scheme such that some library calls and language features are not available for the first several chapters. I felt that this was such a gaping hole in my employability since geeks online develop such strong feelings when an API version is deprecated.

Fortunately, my worries on employability proved baseless. No sooner than my internship did I start working on Android and its API. Then I was into a whirlwind of proprietary MVC and then some networking alphabet soup (hello, TCP, UDP, CIMD2, EMI, SMS, AT codes, ZMQ…whew). And then, in the past few months, some more API here and there. All of which has lead me to the conclusion that documentation—often overlooked, often scoffed at—is incredibly difficult to write, much less understand.

And what would make documentation “good” to begin with? In my opinion, good documentation would be

  1. Friendly to newbies with considerable skill. I add “with considerable skill” because I would not expect any reasonable documentation to start by teaching readers how to program. For a web API, let’s start with a baseline of knowing how to issue GET and POST requests, and maybe parsing JSON. And,
  2. Has a fair amount of short, self-contained, correct examples that anyone on a tight deadline can hack together something reasonably production-ready and that anyone with more time and experience can string together for something fancier. Copy-pastable examples is a huge, huge plus to this point.

(I was sorely tempted to add a sufficient, but not necessary, condition of readers being able to work without referring to StackOverflow but decided against it. Is it really reasonable to expect developers to not refer to StackOverflow, or that they can anticipate a good deal of the unique conditions in which their readers may put their libraries/services/API to use?)

I can name a handful of documents which I think will pass those two criteria. Among them,

  • Android’s documentation.
  • Most, but definitely not all, Python libraries out there.
  • Mozilla Developer Network JS and CSS is something I will find hard to live without.
  • It’s not cool to say this but the Java API docs is definitely above average.
    • And I remember that Sun’s Java tutorial—back when Sun owned Java—is a good jump-off point to the language.
  • Even less cooler to call, is CodeIgniter’s. Anyone remembers CodeIgniter? I’d have to begrudgingly give it to PHP too. Say what you want about PHP as a language but they had usable documentation back when I was actually using it.

I’m trying to come up with a list of those who don’t but I don’t want to name names, especially when documentation is so easy to change1 but, thinking about it, I think I’ve discerned a pattern: they are all, more or less, “corporate data” APIs. And cool companies are not exempt from exposing a “corporate data” API or two.

Common sins of APIs are:

  1. Being outdated. Though I’m inclined to think that frustrations which I’d bin under this label could be due to my slack as well. See I usually just Google-search whatever it is I want to do and work from what seems to be the easiest example to follow from the first page of results. Sometimes, this is StackOverflow so that lets the API writers off the hook. Sometimes, it is really the official documentation. You set things up, copy-paste the code, hit run, see things work through the logs building to that moment of anticipation when the next log should show you the data you are trying to fetch…only for your code to throw an exception. Apparently, in between the time the docs were written and now, they changed the return format of their API without it getting mentioned anywhere.
  2. Not indicating the version for which the docs were written. Slightly related to (1), I stand guilty of this too. Having mentioned my workflow above, when things don’t work, it’s become my habit to check the version for which the docs apply before going to StackOverflow.
  3. Returning unclear error messages. This is a problem that pervades programming in general; at the bare metal, things just either work or not so we created exceptions to distinguish one kind of not-working from another. But even that isn’t perfectly helpful. What do you do when the interpreter tells you it ran into a null pointer in a line of code that has several objects?2 Taken to APIs, sometimes all they tell you is that they ran into a permissions error. But what kind of permission was missing? Was it my API key? Was it permission from the user for our app to access their data? Maybe, permissions error on your OS where your endpoint tried to run a script which not even root has permission to run? Hah, which brings me to the special number in this list which is…
  4. Unnecessarily leaking your implementation to your users. This is special because there is only one (and I hope there will only be one) API I’ve worked with so far which did this. They had other fuck-ups but this is the one which made me question how exactly did my life’s choices lead me to working with them. I know we have a concept of leaky abstractions but asking your API clients to wait for 30s to act on an acknowledgement they received is just sheer incompetence, not an abstraction leaking. Do you even know how to abstract, bro?

Thankfully, if you are working with languages like Python or Javascript, introspection is dead easy which kinda works around the first two. My workarounds for those that fall into #3 has ranged from the obscure (using tcpdump on the connection and debugging on Wireshark) to the fairly standard (excessive logging and StackOverflow searching). As for four…well, thankfully, I was already serving my final 30-day notice when this detail leaked.

To be fair, I’ve had my share of designing a web API for work. I’d admit that there was a phase where our documentation wouldn’t pass my standard3 but when I left I think we were in a state that is, at least, workable, if not passing both my criteria. The title of my post could also be unfair to devs since sufficiently large companies would usually have technical writers who churn out the docs. Having technical writers, however, does not mean that devs have minimal influence on the outcome of the documentation. Based on experience, a technical writer’s job can range from just formatting/proofreading whatever the devs wrote to actually understanding the system they are documenting and actually writing most, if not all, of the documentation.

So, should devs write their own documentation? Why not. The Python libraries that pass my criteria are open-source where, I presume, devs write their own docs. The only problem—at least for most devs—with what I am espousing is that they’d actually have to learn how to write and writing effectively, technical or otherwise, requires empathy. Alas, this would be another blog post on its own.

All that said, I’m at that point in my career when, if asked to work on something you can slap an acronym on, I begin wondering when would Mangastream come around to translating and releasing their Hajime no Ippo backlog. Because best practices, bro, nothing fancy. Best. Practices.

  1. One of the things that came to my mind to call out is Facebook’s docs for setting up a lead gen endpoint. When I was working on it, all they had is a screencast walkthrough of setting up one but then months later, when I had to debug something in my implementation, I found out that they have transcribed the screencast, to my relief. The screencast, being unsearchable to begin with, is definitely not friendly to anyone with a tight deadline (I should know). Whether it is newbie-friendly or not would depend on the newbie’s preference of video over text. []
  2. You reformat your code so that there is only one object per line, heh. []
  3. At the time, the documentation wasn’t solely to blame, I think. The shape of the API then was quite convoluted for a web API that my baseline of knowing GET/POST/JSON would not be enough to work with it. []

“Six weeks? We don’t do projects in six weeks. We usually do them in six months.”

~Mr. Lee, CEO of Azeus, during his meeting with us interns. Words are not verbatim.

Aaaaaannndddd we’re on the final week. We coded last week away and I expect we’ll do the same for our final week. My fingers are now packed with awesome strength, honed from hours of coding. My body, on the other hand, is starting to display symptoms of coffee dependence, as coffee is my mental stimulant during those sleepy hours after lunch break.

Our project is nowhere near finished yet, sadly. And we already scrapped some features at that. Among the casualties in the clean-up was my statistical ranking system. I’m not really disappointed that it got scrapped as I still have two challenging features to implement. And besides, I don’t think I’ve managed to perfect that system to behave exactly as we expect it to; after realizing that Python’s randint returns a uniform distribution I stopped thinking about it but I bet I have a few test cases in which it will break.

To manage all the project’s files, we are using SVN. This is the first time I ever coded with such a large team and I admit that it can be quite overwhelming. The most number of co-developers I ever had before this was 4, making-up a team of five, including me, and we didn’t use SVN that time. The first (and, prior to my internship, only) time I ever used SVN was, ironically, in a pair-programming project.

This is also the first time I ever used a framework that’s being coded as we work, and being coded by co developers at that. The pros:

  1. If there is a function you need but is currently not in the framework, all you have to do is talk to the person responsible for that type of function and you’ll have it at your next SVN checkout. No more awkward workarounds or (worse) waiting for months for the release of the next version.
  2. If there is a bug, or something you don’t understand, do the same as above. No more waiting for forum answers that may never come at all.
  3. It is a learning experience. I don’t really work with frameworks a lot but for those few times I did, I always wondered how they did things* (my current fascination, by the way, is CodeIgniter’s URLs, which are actually class/function names). Since my co developers (with our mentors) made the framework, I can see the code and learn how they did it. While I don’t understand everything about the framework (the jwebsocket-based framework still stumps me), I sure have picked-up some nifty programming tricks.

And the cons:

  1. Since we’re running on a tight deadline, and since framework development runs parallel with project development, some parts of the framework tend to be buggy, especially those made by request (see #1 above). It changes rapidly too: the jwebsocket-based framework has been through a number of deprecations already.
  2. Again, maybe due to the tight deadline, the framework isn’t well-documented, if at all. Though I can ask the person responsible directly, it gets a little embarrassing after a few rounds especially when that person is also working on something for his module—something that is always the case, without fail.

So there. I hope I can finish everything under my responsibility this coming (final) week. I’ll really work hard and smart to beat that!

*Maybe, my hesitation to work with frameworks is because I don’t understand how they do what they do. They’re like magic.

Biggest. Hurdle. Yet.

The base code I was waiting for came finally this week. They seem to have resolved it last Friday, after I went home. However, I spent the better part of Monday improving on a more stable feature trying to beat an afternoon deadline for a demo build. I only started looking at the base code around noon.

The instructions were pretty simple. Extend and override the methods of class Foo and then call method bar() of class FooBar. Sounds easy right?

Well it is supposed to be easy. Unfortunately, things went a bit more complicated for me in this episode of my adventure.

At this point, I am unwilling to continue my story using the optimistic-man voice I am hoping I have sounded like so far. It wouldn’t do the frustration involved any justice. Instead, I’ll be taking a leaf out of the books of those genii-going-madman from the movies and tell my story…

…event-log style (cf. Darren Aronofsky’s Pi)

Monday, 9/16/2011, sometime after lunch. Carefully read through resources and emails for instructions on how to work with the framework we are using. I coded what I’ve understood so far. Right. This should work. Hit “run”.

Monday, 9/16/2011, around 4PM. How many times have I hit run and I still don’t see a single map tile on my AVD? I already encountered this problem when I first worked with Google Maps but I don’t remember how to resolve it. They say it boils down to my API key, which is already there, copy-pasted from the layout xmls of my previous Google Maps work.

And it doesn’t help that AVD3 takes a lifetime to load or that, every now and then, connection to it times out and you can’t test your code on it anymore and the only solution is to close the AVD and wait for another lifetime.

Tuesday, 9/17/2011, morning. A beginner’s mind is a fresh place to come from, Zen says. So, this morning, I tried to address the issue of Google Maps not showing on my AVD. I perused StackOverflow, Android Dev Notes, Ubuntu Programming Talk forums, hell and high water but nothing seems to work for me. I even tried to regenerate my API key! After a few failed attempts at getting Google Maps to show, my beginner’s mind isn’t so fresh anymore.

Tuesday, 9/17/2011, after about an hour. I decided to test my previous guaranteed-working Google Maps code. They didn’t work. Tried to run them on an AVD in another computer. They worked. What?!

Tuesday, 9/17/2011, after a few minutes. Explained the developments in the issue to my mentor. Turns out that I hadn’t set the proper port and proxy. That’s funny since I don’t remember tinkering with the AVD’s settings since the last time I worked with Google Maps. While I appreciate the art in classic cartography, I never thought the sight of a map can make me this ecstatic.

Right. Whatever. Must. Code. Now.

Tuesday, 9/17/2011, around lunch. I can’t figure out what I’m doing wrong. I followed every instruction—extended every class they told me to extend, overrode every method they told me to override—and it still won’t work. I’m caught up in a cycle of read-code-run-ask. I’m starting to feel embarrassed as I repeatedly go to the same person for help. He seems to be the only one who understands what’s happening in the code and I seem to be the only person in need of his assistance. Perfect combination.

(If it’s any consolation, I’m the only one working with his code.)

It won’t work even after I showed him my codes and he nodded telling me it should work. Should.

Tuesday, 9/17/2011, an hour or so after lunch. I decided to run the sample code instead of just studying it and trying to get the pattern. It works flawlessly. What I can’t understand is why it doesn’t work for me. My bad. This code hates me.

Tuesday, 9/17/2011, after about 30 min from last log. Breakthrough. He pointed out that he didn’t really extend and override the methods of class Foo himself. There were already pre-made classes in the framework which did that for us. All I have to do is add my own code, should I need some more functionality/processing.

Wow. I didn’t know that.

Wednesday, 9/18/2011. (At this point, logs will have precise time stamps as it is this day that I thought up of this whole scheme.)

Wednesday, 9/18/2011, 9:18 AM. Succeeded in disabling the sample code. That’s intentional, the rationale being, if I can break it I understand it…

Non sequitur. Turns out rationale isn’t really very rational as I still can’t do what I want to do with the code.

Wednesday, 9/18/2011, 9:42:56 AM. (Time stamp from Android’s console at Eclipse. That’s accurate!) Modified the code some more and then hit run. Console greeted me with the following message: “Installation error: INSTALL_FAILED_INSUFFICIENT_STORAGE”. My bad. How big has our project become!

Wednesday, 9/18/2011, 10:06 AM. I thought I got it but still no. Hmppfff.

Wednesday, 9/18/2011, 10:32 AM. SUCCESS AT LAST!!! Must document how I did it so I can modify further! YEAAAAHHHHHHH!!!! I’m happy again!

<(‘-‘<) ^(‘-‘)^ (>’-‘)>

So. There you go. A story of my descent to madness then rise to happiness for the past few days.

Stay happy. Till next time ~ The Andrei Estioco