Every now and then I am asked to work with other people's code.  Either to review suitability or to fix or extend.  It can be a source of extreme frustration when I come across code that is hard to understand or impossible to decipher.  So here is how to write code to get my teeth grinding.

1. Don't provide any documentation whatsoever - the code is the documentation, right?
   Wrong!  In general clear code can be read, but if someone is coming in cold it really helps to have clearly written documentation, at least on how to install/build/test the code or the configuration options. If I am evaluating a number of options I'm going to look at the documentation first. If I can't figure out how to install it and get it running in a few minutes I'm going to move on to the next candidate.
2. Don't comment your code
   That's all right, I have all day, I can read the code and determine what it is that particular function is supposed to do. Make me work for my pay.  Comments are important. In fact when I write code I often start with the comments, and fill the code in as I go.  This means I have thought about the code and what I'm trying to achieve before I write the code, what does no comments say about you?
3. If you do comment your code, do so sparsely and copy entire comment blocks into inappropriate places
   Yeah, don't give me an even break.  This is just treating your potential audience with disrespect. I don't care that you know how it all works, I want to know how it works and if I read the comments and the code doesn't match it takes me twice as long to figure out what it is supposed to do.
4. Don't use consistent function naming
   If you are going to write good code, settle on a naming convention.  I don't care what the convention is, but stick to it. If I see functions like setTarget and getTarget, then I'm not going to be looking for target_set_value in the same codebase.
5. Don't use meaningful function or variable names
   I once had to maintain code that had variable names like THE_LONG_MARCH and THE_SEVEN_DAYS_WAR.  Very amusing the first time I looked at it, but when I had to figure out why it didn't work, I was far less amused.  The use of a variable or the operation of a function should be clear from its name.

Every one of the above problems I've seen time and time again.  Even in the last few days I've been scratching my head over these issues in at least one product.  We have all been guilty of one or more of these problems, and if we were only writing code for our own amusement it probably wouldn't matter.  As soon as that code has a wider audience, even if that audience is just one person other than yourself, you need to pay attention to the small things so they don't become big issues.