Writing Effective Code
From Zanecorpwiki
Writing effective code is mostly about writing code that it's easy for a fellow developer to follow. This lends to a style of coding that makes code easier to refactor and maintain. The best code should encourage review and refactoring. Developers should want to go to your code to get ideas or, even better, look for areas of potential abstraction.
Contents |
Code as Much as Possible for Humans
Code is for computers. You probably won't ever want to substitute a more efficient algorithm for a less efficient version because it's easier to follow. Yet, once you've figured out what you need to do for the machine, make everything else for the human. Use descriptive variable names, even if they do get long. Chunk your code into functions for the sake of readability if nothing else.
The developers that look at your code later on are secondary to the computer, but the computer is (relatively) agnostic about many of the details. The machine shouldn't always win, either. Big machine optimizations should (almost) always win over tweaks to help human readers because the big human wins are almost always orthogonal to the big machine wins. On the other hand, don't sacrifice significant human wins for small gains on the machine time. For example, even when variable name length matters, as with scripted languages, you should still prefer long names.
Annotate
Annotate your code so that it's easy to follow. Good code will be written with a human reader in mind (see above), but the primary audience is still a machine and often requires a presentation that isn't optimized for humans.
Most developers have an internal standard of when to add comments based on how difficult they perceive a line or chunk of code to be. Your standard, however, shouldn't be can a developer understand this, but can a developer easily understand this.
There's no need be overly verbose--respect that your audience is competent and understand your comments aren't meant to teach. In most cases a few words that point the developer in the right direction are sufficient. Naming/explaining concept or pattern are you using provides can provide the framework easily understanding otherwise opaque sequences.
IDE Windows
No matter how much attention one pays to arranging code, it can become a zero sum game. Pulling code into yet another library makes it hard to see the purpose of all the libraries at a glance. Leaving to many helper functions in a file can make the file to large. Even arranging all the helper functions at the end (or otherwise grouped together according to the language aesthetic) only goes so far because the developer may need to be looking at both areas at the same time, and unless the functions are right together, it won't help much.
That's why we should understand what tools are available to developers when we write. IDE windows mean that we should expect that developers will be able to pull up the various functions in different windows on their own. We should make intelligent groupings in our code, but don't get caught up in getting the groupings and orderings just right. I've never used an editor (and this goes back to 1996 and my Emacs days) that didn't have the ability to split vertical and horizontal windows.
Bonus: IDE Folding
As a reader, another feature I love but which is less common is code folding. IntelliJ has this for it's supported languages, and I'm going to guess that Eclipse probably does. The other editor I use, jEdit, does not and it's about the only complaint I have with jEdit (which is specifically a criticism of the available plugns, but as an end user, that distinction is meaningless).
Cold folding simply means the ability to collapse blocks of code. So an entire class is replaced by the class name and an option to expand it back out. Same with functions. This is particularly useful in a language like Javascript which can have lots of helper functions embedded at many different points throughout the code.
