Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

pdcawley (485)

pdcawley
  (email not shown publicly)
http://www.bofh.org.uk/
AOL IM: pdcawley (Add Buddy, Send Message)

Journal of pdcawley (485)

Friday November 22, 2002
05:38 PM

Coding guidelines

[ #9100 ]

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
The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • 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 [pragmaticprogrammer.com]. What about you?

    -Dom

    • 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.