Friday, June 19, 2009

Preferences On Code Style

Please help me read your code. I know you don't owe me anything, and you can run your code even if it doesn't pass the Agile Otter Sniff Test. I appreciate all of that. But I think that you and I can both do a better job if we're just up-front about things.

I find little speed bumps in most code, and it breaks my fragile concentration . Maybe writing on index cards has made me parsimonious, but now I believe that less is more. I can read your code better if there is less of it, and it's more obvious.
  1. A function should not have many effects on the code. Don't code things into the same function just because they happen at nearly the same time.
  2. You do not have to shoehorn your new code into an existing class. Clear a space for it.
  3. Extract classes when it makes sense to do so.
  4. Use less horizontal space. Long lines and lines with long blank leaders cause my eyes to cross and make me scroll my windows to see if there's something I want to read. This is more important if I'm using an IDE, because I'll have tiled views to the left and right.
  5. Use less vertical space. Don't double-space everything. Don't add meaningless blank lines. All you're doing is making me scroll more. Don't put a space between a comment and the line of code it is explaining. This is more important in an IDE because toolbars and other window tiles take up the top and bottom. Sometimes I'm stuck in a 60x12 space trying to read 120 x 240 functions.
  6. Your functions do not need a blank line after the opening brace and before the closing brace. Get value for your vertical whitespace, as if it were costly.
  7. Stop flowerboxing all your comments. I used to like that, but now the signal-to-noise ratio makes me nuts. A one-line comment should be just one line long.
  8. Do not make needless comments. If the code says what it does, the comment doesn't have to. Face it, non-programmers are NOT going to read your code. Needless or redundant comments are annoying and distract me from the code. I delete them without asking for permission, so expect to lose them.
  9. Consider removing the big banners telling me that the default constructor I'm looking at is a default constructor. I'm simple-minded and particular, not stupid as a rock.
  10. Pay attention to naming. When namespace names and variable names and filenames don't stand apart crisply, I forget which is which. I'm simple-minded, so make the distinctions clear and meaningful. In particular, don't use two names which vary by one phoneme.
  11. The same class names in two different namespaces is confusing. You can't prevent it all the time, but you can try to make sure that when it happens it is meaningful.
  12. Don't be afraid to extract methods, introduce variables, etc to make the code more obvious. Obvious counts.
  13. Don't make me have to remember what functions were called prior to this function call. Relying on other calls to initialize fields to certain values will just tick me off. I can only hold a little context in my head at once. When I'm looking to make a change, I don't even want to hold all of your class' context in my head. I have other things in mind.
  14. You commented out several paragraphs of code, and now I have to skip over all that crap to read the live code. If you need to keep it around, use version control.
Those things help me. How can I make my code more pleasant for you?