More important than universal style guidelines is a consistent coding style within a source code file or project. That is, if you break any of these style rules, at least be consistent about it.
What makes good code good? I’m glad you asked. A nice little article by the late Paul DiLascia sums it up nicely. Read it at:
http://msdn.microsoft.com/en-us/magazine/cc163962.aspx
In short, “all good programming exhibits the same time-honored qualities: simplicity, readability, modularity, layering, design, efficiency, elegance, and clarity.” And the occasional clever hack...
- Write Simple Code
- Write Readable Code
- Write Modular Code
- Write Layered Code
- Write Designed Code
- Write Efficient Code
- Write Elegant Code
- Write Clear Code
- Use Clever Hacks Sparingly
“Uncle” Bob Martin, author of Clean Code and Agile Principles, Patterns, and Practices in C#, recommends writing SOLID code:
- Single Responsibility Principle— PDF
- Open/Closed Principle— PDF
- Liskov Substitution Principle— PDF
- Interface Segregation Principle— PDF
- Dependency Injection Principle— PDF
See also Dimecast SOLID videos.
Simplicity means you don’t do in ten lines what you can do in five. It means you make extra effort to be concise, but not to the point of obfuscation. It means you abhor open coding and functions that span pages. Simplicity—of organization, implementation, design—makes your code more reliable and bug free. There’s less to go wrong.
— Paul DiLascia
Readability means what it says: that others can read your code. Readability means you bother to write comments, to follow conventions, and pause to name your variables wisely. Like choosing “taxrate” instead of “tr”.
— Paul DiLascia
Modularity means your program is built like the universe. The world is made of molecules, which are made of atoms, electrons, nucleons, quarks, and (if you believe in them) strings. Likewise, good programs erect large systems from smaller ones, which are built from even smaller building blocks. You can write a text editor with three primitives: move, insert, and delete. And just as atoms combine in novel ways, software components should be reusable.
— Paul DiLascia
Note: A good guideline to remember here is the object-oriented design practice to “favor composition over inheritance.”
Layering means that internally, your program resembles a layer cake. The app sits on the framework sits on the OS sits on the hardware. Even within your app, you need layers, like file-document-view-frame. Higher layers call ones below, which raise events back up. (Calls go down; events go up.) Lower layers should never know what higher ones are up to. The essence of an event/callback is to provide blind upward notification. If your doc calls the frame directly, something stinks. Modules and layers are defined by APIs, which delineate their boundaries. Thus, design is critical.
— Paul DiLascia
Jeffrey Pallermo proposed a slightly different view on the traditional layered architecture called the “onion” architecture. Instead of viewing an architecture like a wedding cake, view it like an onion, with core dependencies deeper inside and working outward to the more infrastructural dependencies such as data and file access, tests, and user interfaces. Jeffrey presented the onion architecture for the International Association of Software Architects in 2010.
Design means you take time to plan your program before you build it. Thoughts are cheaper than debugging. A good rule of thumb is to spend half your time on design. You need a functional spec (what the programs does) and an internal blueprint. APIs should be codified in writing.
— Paul DiLascia
Efficiency means your program is fast and economical. It doesn’t hog files, data connections, or anything else. It does what it should, but no more. It loads and departs without fuss. At the function level, you can always optimize later, during testing. But at high levels, you must plan for performance. If the design requires a million trips to the server, expect a dog.
— Paul DiLascia
Elegance is like beauty: hard to describe but easy to recognize. Elegance combines simplicity, efficiency, and brilliance, and produces a feeling of pride. Elegance is when you replace a procedure with a table, or realize that you can use recursion—which is almost always elegant.
— Paul DiLascia
Clarity is the granddaddy of good programming, the platinum quality all the others serve. Computers make it possible to create systems that are vastly more complex than physical machines. The fundamental challenge of programming is managing complexity. Simplicity, readability, modularity, layering, design, efficiency, and elegance are all time-honored ways to achieve clarity, which is the antidote to complexity.
Clarity of code. Clarity of design. Clarity of purpose. You must understand—really understand—what you’re doing at every level. Otherwise you’re lost. Bad programs are less often a failure of coding skill than of having a clear goal. That’s why design is key. It keeps you honest. If you can’t write it down, if you can’t explain it to others, you don’t really know what you’re doing.
— Paul DiLascia
There’s so much I’ve left out, but there’s one more thing I hesitate to add. Use it sparingly and only in desperation: the clever hack. The clever hack is when you sacrifice your principles to expedience. When you hardcode some condition or make a call up the layer cake—or commit some other embarrassment—because it works and there’s no time to do it right. But remember: it must be clever! It’s the cleverness that redeems the hack and gives it a kind of perverse elegance. And if the hack doesn’t work, don’t blame me! Happy programming!
— Paul DiLascia
When a previously used dependency is no longer necessary, it should be removed. This guideline has many applications, including:
- Remove unused library references from projects
- Remove unused references in source code (
usingdirectives in C#,imports in JavaScript, etc.) - Delete Unused Code
As code is written, previously used variables become unused, previously called functions become uncalled, etc. Be sure to delete this old, unused code lest it become a distraction for readers of your code.
Any code that will never be executed doesn’t belong in the source files. If the code may be valuable in the future, move it somewhere else, or at least make sure that the code is in the source control history before deleting it, and consider adding a comment describing the code and where to find it.