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


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

Appreciating Rizal...

Nope, this is not an academic post. More of a reflective and wrote-because-i-was-enlightened type post. Anyway, I just passed a paper on Rizal's notion of a nation according to Quibuyen (a local writer who devoted a book -- A Nation Aborted -- on his treatise on Rizal). Chapter 6 was an interesting read, and a definite eye opener. Rizal all of a sudden became interesting, especially to someone like me who could care less. It seems that most of what Rizal aims for and wrote about is still evident in today's Philippines as I see it. I wonder why I didn't get to appreciate Rizal and his work when I was still in high school -- might be the fault of the high school and the curriculum, or might be because I was still considerably immature then. I wasn't able to understand most of Rizal's writings though even if I got to reading them basically because they translated from Spanish to Filipino/Tagalog. I don't have problems with Tagalog, until you put it in writing. I

Reconnecting with people

2021 started with a a good sense of connection for me, having spent time with friends and family in a simple celebration of the oncoming year. The transition from 2020 to 2021 and being able to look back at a good part of my recent history got me thinking about how life has been for me and the family for the past decade. There’ve been a lot of people that I’ve met and become friends with while there are those that I’ve left behind and lost touch with. There’s a saying about treating old friends different from new ones, which I do appreciate now that I’m a bit older. It also means that my relationships with people that I get to spend a good amount of time with take a different shape. This reflection has given me some time and space to think about what it means to reconnect with people. Friends are the family we choose ourselves. — Edna Buchman I have the privilege of having life-long friends that I don’t always stay in regular contact with. From my perspective, if I consider you a frien