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.
CHill...
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.
CHill...
Comments
Post a Comment