I've been thinking lately about a few practices that I have kind of adopted. Not things you see listed all the times, but patterns that you've looked back and said "I'm glad I did that", then adopted for yourself.
I'm not really thinking of the ones you hear all the time, like "Refactoring" or any design patterns listed in common books either, but would include specific refactoring patterns that you find success with but don't hear about very often...
Separate Data from Code. This is one of my biggest driving factors now--my ultimate mantra. I'm not talking about constants you declare in code as scalars, more about identifying patterns where you can extract data and place it in arrays and use them to instantiate collections of objects--eliminating repeated patterns.
This works very well on GUI code, I no longer would ever consider writing "new Button("Click Me")", because "Click Me" is data and should be from an array, as should all the GUI objects and, preferably, most of their locations and handlers.
This pattern allows some remarkable refactorings that are impossible without recognizing what is data and what is code.
My best change was using the single responsibility principle. Each class I write only does one thing so it is really easy to troubleshoot problems when they are broken down into small chunks. Sure I have many more classes now but by properly namespacing them and placing them in folders I can easily manage them. SRP encourages code re-use and really enables unit testing (and I think is a key concept for test driven development)
Never pass around raw/native/library objects (specifically collections). I try to avoid passing around ANY raw java objects that I can't extend and aren't part of my "domain".
A class accepting a "List" gives no hint as to what you should pass in, a class expecting a "CarCollection" tells you exactly what to pass in, and the CarCollection class itself can ensure it's in a valid state with valid items, a List, even a generic List<Cars> cannot. Finally, you almost always want to add methods, when you use raw objects these usually become crappy utilities distributed throughout your code instead.
This has allowed me a remarkable flexibility when it comes to adding features that weren't planned for in the first place.
Errr... document code!
Especially the public API, with a clear definition for each function, and the the list of authorized limit values for parameters.
Even though no other documentation ends up being written, that much can save me when I have to use (or to make other use) my code!
Interesting: the recommandation about
"When commenting: Tell me WHY you're doing something, not WHAT you're doing"
picks up a lot of vote, but this more general recommendation does not.
That would be consistent with what I see amongst the developers I work with:
no one document its API... (or at least, not many ;) )
(I am referring to public API comments, not to internal bits of wisdom left within a code which are simple comments, not documentation)
Simplify your design requirements. Trying to bite off too much for version 1.0 has helped kill a few of my own projects, while my successful applications were built with the minimum requirements in mind. Try to figure out the very core functionality you want to accomplish, and save the rest for later. You'll thank yourself when the simple stuff turns out to be not so simple in implementation. Also, by getting your product out faster you'll have a chance to get more feedback from users, which will help decide which "extra" features are worth developing or not.
Never Pass English Language Up To the GUI Low level code should not be producing user visible strings. Instead, they should be passing up objects with codes that can be translated and formatted at the uppermost level. This way, if/when you internationalize, you can do it in one place instead of hundreds. Also, it means that in an environment where the View level is separate from the Model, you can have more than one Viewer using different languages. For instance, your movie theatre management system could be simultaneously viewed by the theatre in France, the regional Network Operations Center in Spain, the studio in Hollywood, and the support site in Rochester NY.
When commenting: Tell me WHY you're doing something, not WHAT you're doing. What you're doing is already there plain as day, it's called your code.
Code with sources managed under Version Control System!
That way, any refactoring is less an adventure and more a planified effort, with always the possibility to go back or to compare to a stable state.
Always assume that some poor schmuck will have to maintain your code.
Remember, you might be the schmuck that has to maintain the code, give yourself a break, take no "shortcuts", dont use "clever" side effects, avoid cryptic variables, no unrelated comments...
Thread-safe by default. All of my (Java) code is thread-safe unless explicitly documented otherwise. It takes a bit more thinking and sometimes makes the code more complicated, but I go to great length to consider concurrency in every nook and cranny of my (newer) code bases. To this end, the java.util.concurrent package is a blessing.
This pactice, I believe, makes me write better code. Not only do I consider the concurrent failure modes, but I think that simply thinking about the code more leads to fewer mistakes.
Fewer features, fewer configuration options = usable software = maintainable code = used software.
simple. bye.
In OO languages, keep simpler data objects immutable. This builds upon Paul Tomblin's point about keeping code separate from data. Simple data objects are like bits of hard metal currency passed around the more complex agents in your program, in that they're tangible and definite. They're unlike currency in that thin strings attach them to any object that wants them, for as long as the complex objects want. You wouldn't want someone grinding the "Five Cents" off your nickel and etching "Ten Cents" in its place; nothing should change what your complex objects assume about those bits of data.
In OO languages, complex logic objects should have their API be as small and restricted as possible, and what is there should be documented as a contract. This cuts down on maintenance like you wouldn't believe at first. It makes unit tests for those objects possible. The alternative is objects that expose a smorgasbord of methods to others; they may as well be festooned with billboards shouting "Poke me!", and you'll never know what their state is at any given time.
The corollary to this is that you'll be surprised how often extending an existing class turns out not to be the right choice, in the case of logic objects. (It's significantly more frequent for simpler data objects.) For example, queues are one of the simpler data structures out there, and look a lot like lists - but they are not lists. If the list allows random-access insertion and removal, and sorting, and the queue inherits it, then it will have that too, and risks having other objects use it as a list unknowingly. A queue should contain such a list, perhaps, but not extend it; it should have a totally different API - limited, tested, and well-documented.
This has to do more with source control than code writing, but it impacts the way I develop my software:
Coherent and self contained source control commits:
Each time I'm about to develop a new feature or fix some bug, I plan the following two or three programming micro-tasks, and make sure each one is fully contained in a source control commit. Do not mix changes that are not related on the same commit.
Of course I'm talking about commits to my local branches. When pushing to the central repository, you should always commit full bug fixes and working features.
Use meaningful, relevant, human-readable identifiers for variables, methods, parameters and so on. Arbitrary abbreviations make your code much harder to read and understand.
Don't overengineer. Engineer it just enough to get the job done and to be able to maintain it.
Classes are fine, but don't start there. Instead, analyze flow of information. Where does it come from, where does it go to, how is it encoded, and when is it processed?
For example, if some of the information only changes once a week, possibly you could use a partial-evaluation pattern (i.e. code generator). This can be a divide-and-conquer strategy because the code generator only deals with part of the problem, and the generated code only deals with the remainder. Sounds funny, but it can really simplify things (as well as run a lot faster).
Top Down Programming. Some may call it TDD or BDD, but I simply always trying to be focused on what's currently required. Well, my fingers keep trying pulling me down to the metal by saying: while you're here at this peace of code add some special handling etc., so I'm not giving up and telling myself YAGNI YAGNI move back upward to see what's the next thing that is absolutely necessary. Just my 2 cents.
1) Be Consistent. Nothing is harder to change or understand than inconsistent code.
Bonus: Comment WHY and perhaps HOW, but leave comments about defects, who, and when the changes were made to the SCM.
My personal list:
FIRST write a test that goes red. THEN write the code that makes that one test turn green. Refactor as needed. Rinse. Repeat.
Seperate your concerns!
Do not create "UBER" classes which contain a lot of knowledge of your domain, spread it out in logical part, so that each class has a function in the system.
Also try to decouple allot, so you can easily plug in your test/mock implementation for testing purposes.
Keep the data structure loose and simple. Don't rely solely on notifications to keep various parts of the data tightly in sync. It's too hard to prove they're right, and it takes a lot of programming energy. Instead, have diff-style routines that you call once in a while to clean up inconsistencies.
When approaching other people's code I've taken to assuming that I am the biggest idiot on the face of the planet who has never seen a single line of code in his life. That way, whenever I get the urge to "correct" some line of code that seems pointless and wrong, I think to myself
"You know, I'm pretty dumb, and the person who wrote this probably isn't, so maybe I should find out why they wrote it before I go mucking around in here".
Often I will discover that there is in fact a reason for that line of code that I had never considered. Not to mention the number of times someone has "simplified" some piece of my code, only to discover the week before it releases that the code was actually required to handle that one case where if you hit the "o" key at the exact moment that you press OK while simultaneously playing "Eye of the Tiger" in iTunes via your iPod you will crash the application (which is relevant because your customer is a huge Survivor fan who obsessively presses the first letter of whatever dialog button he is clicking on - it happens).
Generalize the problem, write code that solves the general problem and use it to solve a specific case.
When doing design, Create a GUI as one of the first parts of your design. On a whiteboard perhaps, or in simple front-end-only code. This is a GREAT way to communicate with your customers and find out if you are on the same level.
It also becomes about the best project specs you're likely to get.
I'm not saying code before design, the GUI is not actually the first code you write, it's just part of design that you may throw away or redesign when you actually get around to writing code.
Use Subversion or some other sane version control system.
Use Unit-Testing on everything (even Javascript)
Use a Dependency Injection Framework (okay not for JS). This is related to the bullet point above as well, and can allow you to do incredible things like using Aspect Oriented Programming to add and remove log statements very easily, also it helps when handling SQL transactions. (making sure your begin and commit statements are run at the right place in your code)
Keep your team small, but highly skilled.
Communicate with your team as much as possible!
Gone are the days when one could hide away in a cubical and just work on your project, it's all about team work now.
Keep in time with the rest of the world...
Copying and Pasting == Time to Refactor
Make your code as simple as possible, but no simpler.
Code defensively.
Don't try to be smart or clever.
Let go of your ego.
Cheerfully accept criticism of code that you write.
Learn from your colleagues - even the newbie intern has things to teach you.
There's more than one way to test.
When I learned about refactoring, I tried to write good unit tests. But I often found pieces of code that were resistant, but that I really, really wanted to improve...and so I'd end up changing the code without any tests in place. And of course I'd often break something in the process.
I learned two things:
I agree with Joel, Make wrong code look wrong.
The speed difference between reading code formatted in a constant way and code that isn't is ridiculous. Assuming no one went out of their way to make the inconsistently formatted code obscure I'd guess consistent formatting reads over three times faster with a much higher likelihood of detecting a problem.
Consistent object naming and well documented source code. It's not a problem of anybody else reading your code after some months, that person might be you and sometimes you don't know why you did something that way or how something works.
I try to live by the words of Brian Kernighan:
Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.
I summarize to my co-workers as "Clever code kills".
Well designed interfaces are crucial to managing complexity. When the interface between two pieces of code is ill-defined or "loose" things get out of hand very quickly. I've found that perl is especially good a letting you create an entire castle out of matchsticks... In any language, you have to be diligent and protect your code with a clean interface.
design a really well and easy to understand data structure/db structure, then even if your code is whacked, it's still pretty much self explanatory.
Personally, my best "get things done efficiently and organized" is to write the problem's solution out. This takes two forms:
A high level to-do list, crossing off items as they are slain.
Actually coding it on paper first.
It almost seems like I think through problems more completely when I code on paper first than when I'm hacking on a screen. Your mileage may vary.
Reduce the number of possible 'states of being' that can exist
Ensure objects are initialized and consistent the instant they are constructed and stay so until they are destructed.
If you know your objects members are all initialized and valid while the object exists you can write methods to rely on that without worrying.
I often see code where the author doesn't recognize how important object lifetimes are. They expect you to construct an object and then call various initialize methods on it to get it bought properly to life. This means their code is littered with checks to see if members are valid before they're used. All these checks reduce the code to an impenetrable mess.
Defensive programming. I really like to use defensive coding techniques in the style of Design By Contract. It's cheap to put assertions to verify "impossible" conditions, they document your code, and save your live failing fast when something impossible happens.
The best reference I have in the subject is chapter 8 of McConnell's Code Complete Book.
This is a performance analysis practice that leads to better coding practices.
Somehow the idea got around that you can't dynamically analyze performance without a profiler. Not so.
When code is being sluggish, use the simple random-halt technique to find things that take time that are not necessary. You can do this in the normal process of running the code under a debugger or IDE.
Especially in large software, you usually find that, after you fix a few "low-hanging-fruit", the fundamental reason for slow performance is over-design with way too much data structure.
This leads to a better coding practice of minimizing data structure and not over-designing.
Every time you're tempted to write a comment about some long-range assumption in your code, assert it instead.