One aim

The more you share the sadness the smaller it becomes. The more you share the happiness the greater it becomes.

Sunday, June 13, 2010

Top 10 Things That Annoy Programmers

10. Comments that explain the “how” but not the “why”

Introductory-level programming courses teach students to comment early and comment often. The idea is that it’s better to have too many comments than to have too few. Unfortunately, many programmers seem to take this as a personal challenge to comment every single line of code. This is why you will often see something like this code snippit taken from Jeff Atwood’s post on Coding Without Comments:
1r = n / 2; // Set r to n divided by 2
2 
3// Loop while r - (n/r) is greater than t
4while ( abs( r - (n/r) ) > t ) {
5    r = 0.5 * ( r + (n/r) ); // Set r to half of r + (n/r)
6}
Do you have any idea what this code does? Me neither. The problem is that while there are plenty of comments describing what the code is doing, there are none describing why it’s doing it.
Now, consider the same code with a different commenting methodology:
1// square root of n with Newton-Raphson approximation
2r = n / 2;
3 
4while ( abs( r - (n/r) ) > t ) {
5    r = 0.5 * ( r + (n/r) );
6}
Much better! We still might not understand exactly what’s going on here, but at least we have a starting point.
Comments are supposed to help the reader understand the code, not the syntax. It’s a fair assumption that the reader has a basic understanding of how a for loop works; there’s no need to add comments such as “// iterate over a list of customers”. What the reader is not going to be familiar with is why your code works and why you chose to write it the way you did.

9. Interruptions

Very few programmers can go from 0 to code at the drop of a hat. In general, we tend to be more akin to locomotives than ferraris; it may take us awhile to get started, but once we hit our stride we can get an impressive amount of work done. Unfortunately, it’s very hard to get into a programming zone when your train of thought is constantly being derailed by clients, managers, and fellow programmers.
There is simply too much information we need to keep in mind while we’re working on a task to be able to drop the task, handle another issue, then pick up the task without missing a beat. Interruptions kill our train of thought and getting it back is often a time-consuming, frustrating, and worst of all, error-prone process.

8. Scope creep

From Wikipedia:
Scope creep (also called focus creep, requirement creep, feature creep, and sometimes kitchen sink syndrome) in project management refers to uncontrolled changes in a project’s scope. This phenomenon can occur when the scope of a project is not properly defined, documented, or controlled. It is generally considered a negative occurrence that is to be avoided.
Scope creep turns relatively simple requests into horribly complex and time consuming monsters. It only takes a few innocent keystrokes by the requirements guy for scope creep to happen:
  • Version 1: Show a map of the location
  • Version 2: Show a 3D map of the location
  • Version 3: Show a 3D map of the location that the user can fly through
Argh! What used to be a 30 minute task just turned into a massively complex system that could take hundreds of man hours. Even worse, most of the time scope creep happens during development, which requires rewriting, refactoring, and sometimes throwing out code that was developed just days prior.

7. Management that doesn’t understand programming

Compiling
Ok, so maybe there are some perks.
Management is not an easy job. People suck; we’re fickle and fragile and we’re all out for #1. Keeping a large group of us content and cohesive is a mountain of a task. However, that doesn’t mean that managers should be able to get away without having some basic understanding of what their subordinates are doing. When management cannot grasp the basic concepts of our jobs, we end up with scope creep, unrealistic deadlines, and general frustration on both sides of the table. This is a pretty common complaint amongst programmers and the source of a lot of angst (as well as one hilarious cartoon).

6. Documenting our applications

Let me preface this by saying that yes, I know that there are a lot of documentation-generating applications out there, but in my experience those are usually only good for generating API documentation for other programmers to read. If you are working with an application that normal everyday people are using, you’re going to have to write some documentation that the average layman can understand (e.g. how your application works, troubleshooting guides, etc.).
It’s not hard to see that this is something programmers dread doing. Take a quick look at all the open-source projects out there. What’s the one thing that all of them are constantly asking for help with? Documentation.
I think I can safely speak on behalf of all programmers everywhere when I say, “can’t someone else do it?“.

5. Applications without documentation

I never said that we weren’t hypocrites. :-) Programmers are constantly asked to incorporate 3rd party libraries and applications into their work. In order to do that, we need documentation. Unfortunately, as mentioned in item 6, programmers hate writing documentation. No, the irony is not lost on us.
There is nothing more frustrating than trying to utilize a 3rd party library while having absolutely no fricken idea what half the functions in the API do. What’s the difference between poorlyNamedFunctionA() and poorlyButSimilarlyNamedFunctionB()? Do I need to perform a null check before accessing PropertyX? I guess I’ll just have to find out through trial and error! Ugh.

4. Hardware

Any programmer who has ever been called upon to debug a strange crash on the database server or why the RAID drives aren’t working properly knows that hardware problems are a pain. There seems to be a common misconception that since programmers work with computers, we must know how to fix them. Granted, this may be true for some programmers, but I reckon the vast majority of us don’t know or really care about what’s going on after the code gets translated into assembly. We just want the stuff to work like it’s supposed to so we can focus on higher level tasks.

3. Vagueness

“The website is broken”. “Feature X isn’t working properly”. Vague requests are a pain to deal with. It’s always surprising to me how exasperated non-programmers tend to get when they are asked to reproduce a problem for a programmer. They don’t seem to understand that “it’s broken, fix it!” is not enough information for us to work off of.
Software is (for the most part) deterministic. We like it that way. Humor us by letting us figure out which step of the process is broken instead of asking us to simply “fix it”.

2. Other programmers

Programmers don’t always get along with other programmers. Shocking, but true. This could easily be its own top 10 list, so I’m just going to list some of the common traits programmers have that annoy their fellow programmers and save going into detail for a separate post:
  • Being grumpy to the point of being hostile.
  • Failing to understand that there is a time to debate system architecture and a time to get things done.
  • Inability to communicate effectively and confusing terminology.
  • Failure to pull ones own weight.
  • Being apathetic towards the code base and project
And last, but not least, the number 1 thing that annoys programmers…

1. Their own code, 6 months later


Don’t sneeze, I think I see a bug.
Ever look back at some of your old code and grimace in pain? How stupid you were! How could you, who know so much now, have written that? Burn it! Burn it with fire!
Well, good news. You’re not alone.
The truth is, the programming world is one that is constantly changing. What we regard as a best practice today can be obsolete tomorrow. It’s simply not possible to write perfect code because the standards upon which our code is judged is evolving every day. It’s tough to cope with the fact that your work, as beautiful as it may be now, is probably going to be ridiculed later. It’s frustrating because no matter how much research we do into the latest and greatest tools, designs, frameworks, and best practices, there’s always the sense that what we’re truly after is slightly out of reach. For me, this is the most annoying thing about being a programmer. The fragility of what we do is necessary to facilitate improvement, but I can’t help feeling like I’m one of those sand-painting monks.

Source: http://www.kevinwilliampang.com/

No comments: