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

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

So much for that...

I just came home from the seminar regarding my proposed load balancing algorithm. I tried to get as candid as I can, but still half of what I said was jargon -- which made me explain the thing in layman's terms and using more colloquial examples. I was wearing a black suit, (chinese collared americana suit that is), gray slacks, black leather belt (perry ellis), and leather shoes (by bristol). I'm beginning to sound like a caption to a fashion mag's pic, but I digress... So there I was, waiting for the seminar to start. As a speaker, I conducted myself properly and tried to get things cleared out with my co-presentors. I was asuuming that they knew at least half of what they were supposed to talk about, and that they knew how to speak in front of a crowd. BUT NO... I sat through two presentors, the first one reading the presentation of the projection, and then doing no explaining whatsoever. I didn't get that because she prepared her own slides, and prepared the hand

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