Posts tagged ‘code’

Documentation - Programmers PLEASE Internally Document Your Code!

Okay, so basically, this is just another rant in the long line of rants that no one listens to in life. Still, it’s my blog and if I want to rant, I can. So nya!

For a while I’ve had my head buried in someone else’s code. Ugh. Yeah. We’ve all been there. (We as in programmers at least.) When you’re lucky there’s good use of whitespace, good use of descriptive naming, and so the code pretty much documents itself. If you’re really freaking lucky there’s even enough comments added to the code that you get a good idea of what’s going on. And if you’re really really lottery-winning damned lucky there’s clear and concise internal documentation.

I admit, I’m not always nice enough to go the whole nine yards. Sometimes I skimp, because the code working is more of a priority than the code being maintainable.

But still, I’m a nice guy. I’ve been around the block long enough to know that I won’t always be the one maintaining my code. And sometimes even when I am, code can get complex enough that I won’t necessarily remember all of the ins and outs a year or two later. So I generally make an effort to internally document my code.

I wish everyone was as nice.

As I said, I had my head buried in someone else’s code. Code that, while (mostly) functional, is only a step away from the vagueness of formulaic programming. Code that (and mind you, this is in Python) uses lists (Python’s version of arrays) to store random variables in, like they were freaking FORTRAN common blocks! And I’m not even sure the author knew what a comment character looked like when he wrote it all.

Yes, it was that nerfed. No, I’m not exaggerating. Ye gods I wish I was.

And all I could think about as I added internal documentation and renamed variables to be self-documenting as I wheedled my way deeper and deeper into the code that wasn’t working right, was “Why the hell couldn’t this code be a little easier to maintain?!

Ugh.

Still, having once upon a time, strangely timed right before male pattern baldness and grey hairs began creeping in, I had the joy of performing tasks like converting 16-bit x86 Assembly code to 32-bit and finding C++ libraries that could replace as much of the Assembly code as possible. Assembly code that wasn’t documented. Used in FORTRAN 76 code with that reverse if-goto logic because it didn’t have if-then-else logic yet. FORTRAN code where sometimes the authors commented according to that reverse logic, and sometimes according to modern order … only without saying so. So you never knew if a comment was explaining as it was, or as it should be - but wasn’t. FORTRAN code with common blocks that didn’t even always match up correctly. And spaghetti goto and continue statements all over the place. That in turn used the undocumented Assembly code.

I think it’s safe to say I’ve seen hell. And so my recent delve into someone else’s Python code could at least be said to be more like purgatory. Or maybe more like the second or third circle of Dante’s hell.

And then as I returned to some of my own code to work on adding new features, I found this lovely refreshing oasis of reason and sanity.

If there’s one message, even just one little message, that I could get across to all computer programmers the world over, it is this:

DOCUMENT YOUR DAMN CODE!!!

Thank you.

Dualcore - Do You Get It? Do You NEED It?

A picture of the insides of a dualcore Opteron CPU.

They’re as common as chips today. Dualcore CPUs are everywhere you look. They’re almost the standard now, and quadcore (or higher) are the much ballyhooed upper end. But do you really know what a dualcore processor even is? More importantly, do you actually know what having one means? Here’s a little help for the common (and perhaps not so common) woman and man.

At its heart, a dualcore processor is simple. Take two computer processors. Squish them together. Give them one socket to plug in to so that seems like they’re one processor. Now you have a dualcore CPU. It’s literally two computer processors in one. How these two processors talk to each other (and everything else in your computer) varies widely. For the most part it makes little difference. Oh sure, geeks can argue the finer details of this until they’re blue in the face, but when it comes down to the performance that you and I see, the technical details matter very little. In high-use servers they matter. In desktop and laptop computers, they don’t.

Now, you might be thinking this is great. Two processors in one, that’s like double the processing power. So everything should run twice as fast. Well, sorry, but wrong.

Yes you have a theoretical doubling of performance. There is twice as much of everything there. But that double is still split in two. And more often than not, a single task cannot be split into two for both cores in your dualcore to work on simultaneously.

At the risk of getting into too much technical detail, I’ll break down why. There are two ways to write a computer program. The first is called single-threaded. (A thread is like a strand of code.) Single-threaded programs are easy to write. They were the first kind. All logic flows in a simple easy to understand manner. You calculate A. You perform A. You calculate B. You perform B. It’s all very straight forward. The behavior is very easy to understand and predict. And the only flaw to this method is that because the logic only runs through a single thread, only one core at a time can run this kind of program. In a dualcore CPU the other core will sit there and twiddle its thumbs.

The other way to write a computer program is called multi-threaded. The program is in effect broken down into smaller part-programs, called threads. These threads are then woven together by a lot of code to synchronize and control them. Because the program is broken down into parts this allows each core to grab at least one part of the program for itself, so no core sits idle. The gain is that in computers with multiple processors or a processor with multiple cores the program, as broken into threads, can run parts on each processor and/or core, effectively using a lot more of the resources available. The downside however is many fold. On a single core processor where there are no additional resources to be gained, the overhead of timing, control, communication, and synchronization of the threaded parts causes a loss in performance. Also all of this overhead creates many new places in the program for things to go wrong or even break, meaning a lot more bugs are likely to be in the program. But on top of that all, the job of the programmer to sort non-linearly through this multi-threaded code to find and fix bugs becomes exponentially more challenging than stepping through linear single-threaded code. So this all adds to a vast increase in development time and cost of a program, as well as greatly increasing the likelihood that it will be sold with unfixed flaws.

But that still isn’t all. On top of it all is the simple fact that not all computer programs lend themselves well to being broken into smaller pieces. Some programs do. Programs that repeatedly perform the same tasks over and over for example, can run several instances of those same tasks simultaneously in a multi-threaded program to fully utilize a dualcore processor. And programs that perform a vast multitude of very simple calculations that do not depend upon each other, such as the artificial intelligences that run opponents in a game, can also be split well into a multi-threaded program that will well use a dualcore CPU. However, many programs don’t perform tasks that can be broken up. One answer always depends on the previous, and so forth, so that the mathematics cannot be split up. While other programs (like word processors, email, web browsers, et cetera) simply don’t do much and are always just sitting there idle, waiting for user input. So they have nothing to gain from multi-threading.

And finally, one thing that often happens is that when you get a dualcore processor, each core actually runs slower than a processor of equal value with just one core. And since most programs are single-threaded and thus can only use one core at a time, they will run slower on that slower-clocked dualcore than if you had that faster-clocked single core processor.

So in light of all of this, what does having a dualcore CPU actually give you?

Well, for starters, switching between programs should be much smoother. For people who multi-task it will make a notable improvement in the snappiness and responsiveness of switching back and forth between programs. It also allows multiple programs to better run at the same time. Since today we have so many programs running in the background (anti-virus, firewall, chat and IMs, email, audio player, and so forth) a dualcore processor allows you to run what you want to run unhindered by all of those little things. And, of course, there are some programs like image editing software and some games that can greatly take advantage of both cores of a dualcore processor.

So the next time you go to buy a new computer or upgrade your computer processor, take a real hard look at what you do on your computer. Are the programs you run going to need a lot of processing power? Are the programs you run multi-threaded? Are you a multi-tasker that runs a lot of programs simultaneously? The answers to these questions will help you better choose the computer processor that you need.