Skip to main content

The Hard Way...

Many people will agree to the age old addage that "there are many ways to skin a cat". In programming, and even in system administration, there are different types of programmers and different types of administrators. Paintors, poets, journalists, they each all have differences in styles. Somtimes though, too much diversification leads to chaos. Which isn't necessarily a bad thing, it's just more inconvenient to have "too many ways of doing things".

I am currently working on a software development project which takes a lot of time designing and implementing. Although there is a general approach to what is going to happen, there are a few things that have to be put in place before you even write a single line of code. And one of these is coding standards -- how do you document your code, what to do in certain situations, etc.

Through the software development process, I have found out that proper documentation of code is really REALLY necessary. A job ago, I had to deal with the source code for something I only encountered for the first time, and had to hack at it to make it work the way my boss wanted it to work. It was open source (public domain even IIRC), but the code didn't have very useful documentation for developers. And when reading code without documentation, usually the brain gets overworked because it's meant to understand concepts -- not act like a compiler. Although you can train your brain to do automatic decoding and syntax validation, human error is still the main source of problems in software development.

I thought it would change with my current job, but then since there are deadlines to beat, processes to follow, and guidelines to abide by, it becomes a lot harder than I originally thought. So anyway, I started documenting my work the hard way -- with pencil and paper. It was all nice and dandy for like the first week, but I still wanted to read documentation as I read through the source. So I scrapped the notebook, put it in the drawer, and I instead used inline comments.

The bad thing about inline comments is that they don't usually give very nice descriptions about what the actual thing does -- sometimes you're in full logical mode, that the comments already look like code. Some other times, you feel like in novel-writer mode that the code now looks more english than ever (which is supposedly a good thing, but when you need to type it down, that's something else).

So today, I resolved to write the documentation using doxygen -- doing inline documentation, and when the code is compiled and works according to the unit tests, the external documentation is produced. I quickly relive the days when I could just write the javadoc for the classes first before ever writing the implementations, and then working from the API documents/specifications instead. This way, I had a clear idea of what the classes/interfaces/subclasses/methods would be doing, and will be more productive hitting two birds with one stone.

But then it's all fine and dandy when you're the only person working on code without documentation. You're reading your thoughts, and it's a coherent mess to others. But consider if your documentation was as cryptic as the code itself? I don't even want to begin imagining.

And it's worse enough that I inherit code that doesn't have documentation. They don't work "right" yet, so I had to make the necessary changes to "core components" with minimal supervision. Now, more than ever, I have to deliver -- and hit two birds with one stone yet again.

I certainly hope I can get back to the most productive form in my coding life in the next few days... Not that I have to because there's a deadline or anything, but more because I miss it too much. I certainly have to get back to writing more instead of reading more in the coming days to be able to finish what I want to be able to accomplish by the end of the week.



Popular posts from this blog

Writing Again

It's 2019 and I just realised that I've not written on this blog for a long while. I feel a little bad about this so I'm picking it back up again. More importantly, I've limited my social media to just Twitter (I've deleted all my Facebook-related accounts) and will be writing more on the blog instead of engaging in other social media sites. If you want to reach me directly, you can also reach me through my account for encrypted communication. If you have my phone number, you can also contact me through Signal. Quite a number of things have happened in the past few years and here's a quick update on things that I can share:

I've been working on XRay, a function call tracing system now part of the LLVM project. This took a good two and some years of my time at Google.Most recently I've moved to the Chrome Operations Team still here in Google Sydney. I can't give specifics yet of what I'll be working on, so stay tuned.There've been c…

A Passion Project

I was so moved today by the prospect of a passion project that I took some time on a Friday night to get it done. Let me present the #RedJeans project over at I've found myself wanting to work on a project that came purely from the heart and one that was very dear to me, something that is personal, and connects with a larger community of people in the world.
The idea for came to me as a hint when I was writing up my reflection for 2018. I realised that I didn't spend quite as much time identifying with and working with a community. I did a bit of soul-searching and found that one of the activities I really enjoyed and cherished in years past is donating blood -- and I keep wondering why not more people do it. It was an idle thought but then a conversation with someone where I described why I wrote down "donate blood more often" in 2019 became an idea where instead of just me doing it, how about if I get my friends to do it too?

I left it a…


Until very recently I believed that I needed to be on top of the latest news and happenings not only in my field (computer science and software engineering) but also in as many things as I can be on top of. This meant subscribing to all sorts of magazines, newsletters, YouTube channels, Twitch streamers, watching TV and live sport events, etc. — I was on top of a lot of the latest happenings, trends, news, interesting developments. I was having fun and I felt busy. What I did not feel was particularly effective nor productive. I felt like I was consuming so much information with the thought that it might be useful someday. When I was younger this wouldn’t have been an issue but I realised that ever since I’ve started taking stock of what I’ve been spending my time on, that a lot of it I’ve been spending just staying on top of things that I really didn’t need to be on top of. This article is about some of the realisations I’ve made in the course of exploring this issue of “FOMO” or th…