Skip navigation

Tag Archives: web development

Don’t Devs Know How to Write?

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. [↩]

More Django

For February I tinkered with Django, arguably the most popular web framework for Python. Prior to this, the only web framework I’ve had experience with is CodeIgniter and one proprietary JSP-based framework.

In an earlier post I covered installing Django. Nothing much has changed between then and now except that the most recent version of Django, 1.5, now supports Python 3! The first for Django ever. But I’m sticking with Python 2 for the time being.

Note: I tried learning Django last August, in an afterthought project with goals loftier than what my resources could have achieved. Needless to say, I never got too far with it. It was this which prompted me to specify a mini-project I’d use to learn web frameworks (any web framework). I’m not sharing the specifics of it now but you can gather what you can in my sandbox repository.

The Admin Site

One nifty feature of Django is how it creates an admin site automatically for you. On my CodeIgniter projects, I’d pattern the users table something like this, borrowing from Linux file systems:

CREATE TABLE IF NOT EXISTS users(
    -- Some project-specific fields here
    create_time TIMESTAMP NOT NULL,
    last_updater INTEGER NOT NULL,
    last_update TIMESTAMP NOT NULL,
    can_read BOOLEAN NOT NULL DEFAULT TRUE,
    can_write BOOLEAN NOT NULL DEFAULT TRUE,
    can_exec BOOLEAN NOT NULL DEFAULT FALSE,
    PRIMARY KEY (userid),
    FOREIGN KEY (last_updater) REFERENCES users (userid)
    -- Yes, apparently, MySQL allows you to foreign key recursively
);

If I’m really feeling up to it, or if the project requires (never had it tho), I might even implement user groups. But even with this, I can already define 23=8 types of users, which is already way more than what one project usually requires. What I’d normally do here is to designate can_exec privileges to admins. Way neater than maintaining different tables for different user types and then giving admins backdoor log-in pages—one of the naive approaches I used when I first started designing databases for apps.

Django automatically covers this for you, user permissions, groups, and all. The structure becomes a bit different though, and I find permission management way more complicated than my binary-scheme. Take a look at all possible user permissions in Django:

django_permissions

Look at how many that is, and realize that there is still a scroll bar!

What Django basically did is to allow you to specify add/change/delete permissions for every table in your database. Note that due to how Django enforces code modularity (see below), the number of tables in your database could easily blow-up.

Code Modularity

Perhaps one of the most confusing things I encountered as I tried to learn Django was how it distinguishes the terms “project” and “app”. Normally, I’d talk about an “app” being a “project” for some party. But in Django a project is a collection of apps. I had a hard time designing my project around these terminologies even after reading discussions at StackOverflow until I realized that perhaps a better term for “app” would’ve been “plug-in” and there’s really nothing stopping you from making your project as one big plug-in.

With the side-effect, of course, of your app being non modular and probably not well-factored. So, yes, the way Django handles things enforces the nice practice of modularity. Nice to take advantage of it, though it may be too time-taking to wrap your design around Django’s rules.

Django also enforces a form of Object-Relational Mapping (ORM). In fact, you don’t need to write a single line of actual SQL code to get your database up and running—all DB creation is done through the ORM and manage.py . This even allows you to easily switch DB back-ends. Then again, as with above, not all projects would fit well for an ORM approach.

Overall?

I find Django pretty neat given that you only need minimal set-up for this whole bunch of admin stuff. But then I haven’t had much time to explore it although I’ve volunteered in a (non-work, non-paid) project that might use Django pretty extensively. Guess I’ll get more Django this month. Let’s see.

…And I’m Live (Again)!

There. I beat my deadline. The main site is live again! Yay!

But that is not to say that I got this without glitches. Let’s see…

After feeling good with the WordPress site I developed locally, I pushed it live by uploading all my local files (and changing password-related configs) to my server. However, I noticed that all my links start with “localhost”—they are pointing to the local version I developed. The only page I can view from my remote site was the home page.

The fix is easy enough. I just had to change all option values in the wp_options table of my WP site so that they don’t refer to localhost. To that end I ran the following query in my database:

UPDATE wp_options
SET option_value = REPLACE(option_value, 'localhost/', '');

Note: be careful when running queries like this. The pattern matching went fine for me but some future version might use the term ‘localhost’ for something else. Always back-up before running! Also, you could’ve set this option up in your WP Admin. Just go to Settings -> General and change the URL-related settings. I wasn’t able to do it in this case because even the WP Admin was getting redirected to localhost!

So, after running that, I got my links good. However, clicking on the links returned a status 500 error (Internal Server Error)!

Googling around, it seems that this has something to do with my .htaccess . The .htaccess is a config file for web servers famous for allowing URL rewriting. It’s the magic behind http://skytreader.net/journal/post-title instead of http://skytreader.net/journal/post-title.php. You can also do cool (or sick, depending on your tastes) things with it like having pages with a .exe extensions (or pointing unsuspecting users to a normal .html page but is actually a sketchy .exe download). Here’s one tutorial I’m quite fond of.

Anyway, my .htaccess looked like, this:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /skytreader.net/
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /skytreader.net/index.php [L]
</IfModule>

Now, I had no idea what to do with my .htaccess to prevent the status 500 from happening. Thank goodness that kodeplay itself is WordPress-powered. So, I just patterned it from kodeplay’s .htaccess:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>

Aaaaannnd voila! Main site up and running! (Though, I won’t be surprised if there are still bugs with my launch.)

It seems that WordPress has a tutorial for migrating WP set-ups. Guess I should’ve read that first no?

Now, a TODO: Write a new entry on my main blog. The most recent one is now more than a year old!

Removing Draft Pages From WordPress’ Navigation

Still working on my revisions for my personal site. It was on full throttle last December but had to take a backseat due to work and something I’m preparing for. Oh well…I’m trying to meet a personal deadline of end-of-this month to mid-February (Feb 16! Mark the concrete date!).

It’s not exactly a tough project but, being the OC guy I am, I’m making sure all ends are ironed well and that’s what’s taking my time. To meet my deadline, I had to cut certain pages (not posts) for which I only have a vague idea as to the content they’ll hold. It feels so long since I did some creative writing.

Now, I ran into a problem removing them from my nav bar (since I don’t want users to see not-even-baked pages, right?). I thought that marking them as “draft” would do the trick. However, they remained on my nav bar.

I’ve been looking into the database and how WP queries for the navbar’s contents, to no avail. There are forum posts regarding this, both I’ve found to be two years old, not to mention not-at-all helpful. That’s when I realized that, last December, I was able to customize my nav bar from the CMS itself, as opposed to hacking the code.

appearance_menus

After some clicking-around the CMS I found what I’m looking for in “Menu” under the “Appearance” tab. You should see some click-and-drag interface for managing what appears on your navbar.

It seems that publishing a page automatically adds it to your navbar but marking it as “draft” does not trigger anything. To make things worse, users not logged-in as an author will hit a 404 if they click a “draft” link. If you are a registered author on the WP site concerned, you’ll still see the actual content. Tsk. First timers might miss the fact that their users will hit a 404.

That’s all for now. Keep coding ~Chad.

Working with WordPress

If you’ve been anywhere near my main blog recently the front page has been looking like this for quite some time now

screenshot_skytreader

Yeah. I’m currently redesigning the website. I don’t know why. Guess it’s just that the look and feel I designed when I was just in my sophomore year in college is not me anymore. Tsk.

Anyway, this is the fourth time I’d be redesigning my main blog ever since I got my mind around blogging. I started blogging when I was in third year high school. Four versions in five/six years? Not bad, I say.

This time, I’m relinquishing controls over to WordPress. The first two “versions” of my blog were all static HTML plus some JavaScript. And it was hosted at GeoCities. The third one had some CMS/parser I wrote using Java, the result of which I’d upload using FileZilla to my own bought webspace. It was in PHP and XML—no databases. The CMS/parser was one hell of spaghetti code; it’d break at corner cases every now and then and I never got around to fix those bugs since, hey, I can live with it. Come to think of it, as I switched machines over the last few years, I’m not sure if I still have the original source codes. I only have the jar file.

But I’ve been woolgathering. My whole point here is to note what I learned with tweaking WordPress.

Where do I start?

Depends on where you want to go. Don’t want your blog posts on the front page but, instead, have some dedicated page for it, featured on your nav bar? WordPress got you covered easily. Just go to “Settings” -> “Reading”, and you should see something like this:

reading_settingsPretty self-explanatory eh?

But what if you have already have a theme which displays your latest posts on the front page but you just want to customize it somehow? Enter, WordPress’ The Loop.

Put simply, The Loop1 is what is responsible for displaying the posts in your blog. You can invoke The Loop in many ways. What I’m using for my main site is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<?php
     $temp = $wp_query;
     $wp_query= null;
     $wp_query = new WP_Query();
     $wp_query->query('posts_per_page=5'.'&amp;paged='.$paged);
        if($wp_query->have_posts()):
            while ($wp_query->have_posts()) :
                $wp_query->the_post();
?>
...
<?php
             endwhile;
         endif;
?>

Again, pretty self-explanatory. Note that this uses PHP’s templating syntax: you can write HTML in the position of those elipsis and they’d be written at every iteration of the loop, if they apply. Also note that I could have used the more-common “curly brace” syntax when writing loops and conditionals but, for templating, it makes more sense to ditch this tradition and go ending blocks with the end syntax as this makes it cleaner to distinguish which block you are ending.

So, what can go inside the loop?

This is where you’d typically print out your blog posts. WordPress provides a host of the_* functions for you to access the parts of your post. All their names are very self-explanatory. Of note are:

Putting it all together

If you want your theme to display your posts on the front page, you’d have to put The Loop in some file like “home.php” or “index.php” found at the wp-content/themes/themename of your WordPress installation. So, say you want a basic list of recent posts that show the title (which links to the posts “solo” or “permanent” page), author name, and the contents, you’d end up with something like this inside The Loop:

1
2
3
4
5

<h1><a href=<?php echo '"'; the_permalink(); echo '"'; ?>>
    <?php the_title(); ?>
</a></h1>
<?php the_author(); ?> <br />
<?php the_contents(); ?>

But wait! I’ve too many posts!
This is the time you handle pagination in your blog. To display the “pagination links” (as I call them), you have plenty of options (which are, again, very self-explanatory):

Note that WordPress is smart enough not to display a pagination link if it does not apply (i.e., if no posts are newer/older).

404 Trouble

When you click on your pagination links, it may happen that you get a 404 (Not found) message. This is easily fixed.

At line 5 of my The Loop code listing above, I indicated the number of posts I want per page. This value should be equal to what is set in your WordPress settings. At Settings -> Reading, see the value “Blog pages show at most”.

Is that all?

By now, this should be good to deviate a bit from the themes you get. You can do more by tweaking the CSS of your theme though if you had to use someone else’s theme I wouldn’t advice intensive CSS tweaking (you’re probably no designer). But well, whatever floats your boat.

  1. Can’t help it but WordPress’ terminology reminds me of another “The Loop” in my geek life: The Game Loop. But that is for another time entirely. [↩]