I've been looking at long lists of coding guidelines in other places, and it got me to thinking about my own rules of thumb for coding. I think of them as a list of short thoughts to get me in the right frame of mind to code.
- You Never Code Alone
- Always remember, even when you're the only person sat at the keyboard, that you are working as part of a team with those who will be maintaining the code. Treat them with respect and make their life easy. That means: don't assume they're fools and don't assume they don't know the programming language. Assume instead that they have roughly the same level of skill as you and hopefully a little more -- after all, the future maintainance programmer will probably be you. However, do assume that they don't have the entire state of the project in their heads like you do right now.
- Don't Repeat Yourself
- Naming is Really Important
- Spending ten minutes now to come up with the right name for something will pay for itself in the future.
- Work on one level at a time
- In a particular method, concentrate on making the flow of the method as clear as possible. Push details into helper methods, don't worry if those methods are really short, worry instead that you're about three levels of braces deep already. Pushing something into a helper method gives you an opportunity to come up with a really good name, and that means you won't have to use a comment.
- Comment only when absolutely necessary
- If you find yourself seasoning a method with comments then stop and think for a minute. Try and find a way of expressing your intent more clearly in code. Save comments for answering 'why' questions; if your code can't answer the 'what' questions by itself then it probably needs more work.
- Write the tests!
- If you don't have a test for it, how do you know you're doing it right? This is specially important when you come to change how something is done. But don't forget that sometimes the tests are wrong.
- Everything else being equal, return
$self
- And fail with an exception. I know, it looks like a makeweight. But every time I've ignored this guideline I've found myself regretting it later.
- Fix it now!
- If you come up with a better way of doing something that means changing a pile of other classes, then change the pile of other classes. Don't live with broken windows or you will regret it later. Don't leave long blocks of commented out code and other cruft lying around -- you have revision control for a reason
- Decide later
- Unless you absolutely have to decide now. But don't be afraid to change your mind
- Solve today's problem
- Don't worry about tomorrow. So what if, in three weeks time you have to redo some of what you did today, it's not like you're building a house.
- Use a revision control system
- CVS, Subversion, RCS, perforce, SCCS I don't care what you choose, but choose. Revision control is not an option.
- Use your judgement
- Consistency is good. Guidelines are good. But one of the measures of true skill is knowing when to ignore a guideline or dispense with consistency
Pragmatic Programmers
Dom2 on 2002-11-23T11:20:17
I agree wholeheartedly with most of those. I've been trying to follow similiar sorts of rules myself and it's really paid off for me. Particularly the stuff about commenting showing a lack of clear code.
I got most of my inspiration from The Pragmatic Programmers. What about you?
-Dom
Re:Pragmatic Programmers
pdcawley on 2002-11-23T13:42:51
Yeah, I got that one. Other inspirations were the white XP book, Smalltalk Best Practice Patterns, The Practice of Programming, The Timeless Way of Building, A Pattern Language, Zen & The Art of Motorcycle Maintainance, The game of Go (decide later' is a very Go-ish maxim...) and probably a whole pile of other influences.
