September 25, 2006

Coding Conventions

I got following content in one of the university article. Thought its good to blog it so that can (make people) refer easily..

1. Make Your Code Look Like Other People's Code

Nothing hurts readability and maintainability more than developers mixing and matching coding styles in a file. Think of the guy who's going to come on this project after you. Okay, you have a prettier way of implementing that event handler.... So what? Two years from now, other developers will read the code. They'll wrap their brains around the coding standards used in the files--until they come to yours, which will make them scratch their heads and waste time figuring it out. Your's will probably look like a mistake and be treated like a bug.

When you start on a new project, get the coding conventions document. Read it. Then forget it. Scroll through the file to see what style is actually used in the project and write your code like that.

If you feel like reformatting the existing code to suit your preferred coding style, refer to rule number 10.

2. Use the Simplest Design Possible

Don't try to be overly clever when you're solving a problem. Just find an easy solution and use that one. Ignore the temptation to craft a complex work of art that will amaze and dazzle your teammates.

This often happens when developers try to optimize prematurely. Developers think that this function is too slow and bloated, so they write some complex (and likely efficient/small) piece of code. It may be elegant code, but if the design or algorithm is too complex, no one will understand it, much less be able to maintain it.

This same point counts for developers who see a problem and want to invent a framework to solve the current problem and any similar problems in the future. Don't do it... yet. Unless you can see several good known examples where this framework will be used in a future sprint, you will only waste time and effort. Wait until you start working on the future problems before creating the framework and refactoring existing code. This can be done safely if you have good unit tests. You do have unit tests, right?

If you feel that you must write some insanely complicated, highly optimized, inline assembly code, refer to rule number 10.

3. Don't Re-invent the Wheel

Always use existing APIs and class libraries. Developers are sometimes tempted to show off their coding kung fu, but inventing a new way to sort only wastes time. Not only will you waste time solving a problem that's already been solved, you'll waste even more time fixing the new bugs your new "better" way introduces to the code base.

Existing APIs and class libraries have already been tested and documented. And everyone knows them, so when you use them, your application will be easier to maintain. An easy-to-maintain application is good news for your team, your client, and the person who will have to actually do the maintenance.

4. Document Your Code

As my wife says to me, people don't know what you're thinking--you have to tell them. You can't always see the logic behind a particular piece of code from the code itself. Unless you're a mind-reader.

Always document your design, implementation, and assumptions. Think of the poor developer who will inherit your code two years from now. He won't know that you intentionally passed bad parameters to that Win32 API function to take advantage of some undocumented, but badly needed API functionality.

Code that's difficult to maintain might as well be a bug.

Keep the documentation up to date. It may cost time to write clear, concise, and correct documentation, but this time will be made up in debugging and maintenance mode. If you let your documentation get out of date, it'll be harder for future developers to understand the code and work through all the design/implementation assumptions made. You also run the risk the code will just get re-written by the maintenance team because they couldn't understand what it was trying to do, which might introduce new bugs.

If you feel you must write some insanely complicated, highly optimized, undocumented inline assembly code, refer to rule number 10.

5. Keep Security In Mind

Check your routine's input for length and correctness (and content, if required). Make sure you read the documentation for the function you're going to call for deprecation or security warnings. If a more secure version exists, use it!

Taking these extra few moments to secure your code saves time and money down the road. More importantly, it saves your company's reputation, and maybe even your job.

If you feel you must write some insanely complicated, highly optimized, undocumented inline assembly code that doesn't check its inputs, refer to rule number 10.

6. Work In Increments

Don't try to write the entire feature or user story in one fell swoop. If possible, break your feature into increments that could be coded in a single day. This helps enforce a simple design, increasing correctness and maintainability while making it easier for reviewers (see rule 8) to understand the problem and solution.

When you break your feature into one-day increments, aim for complete code. Complete code doesn't mean finished code. The key is to produce code that could be introduced into the code base without causing regression errors.

If you leave part of a feature to be implemented later, mark it using a tag that is common to the whole team. It's then easier to realize/identify what's left to do. At Macadamian, we add a comment with the "TODO" prefix.

If you feel you must write some insanely complicated, highly optimized, undocumented inline assembly code that doesn't check its inputs, in one big patch, refer to rule number 10.

7. Work In Iterations

Okay, so you're already working in increments. What's the point of working in iterations? Well, unless you are psychic with a freaky mental connection, then you won't get what the customer wants on the first try.

Instead, structure your work iteratively within your increments. For example, if you're working on a web application that interfaces with a database, do only the UI in your first iteration. Don't implement all the functionality. This way the customer gets to see what the UI looks like and fine-tune it before you waste any time implementing the backend.

If you feel you must write some insanely complicated, highly optimized, undocumented inline assembly code that doesn't check its inputs, in one big patch, that doesn't actually work the way the customer really wants, refer to rule number 10.

8. Have Your Code Reviewed

I'm a big believer in code review (see the sidebar entitled "Code Review"). All code should be reviewed for correctness, maintainability, and sound design. The sooner you find and fix a problem, the cheaper it is to correct it. Another set of eyes is bound to catch errors that you've missed, and to double-check you've followed rules 1-7.

************************************************

Code Review

The company I work for, Macadamian Technologies, has its own method for code review. . But our's isn't the only way. Whether it's Fagan Inspections or something less formal, code review is one of the best quality practices in the industry.

************************************************

If you feel you must write some insanely complicated, highly optimized, undocumented inline assembly code that doesn't check its inputs or work the way the customer really wants, in one big patch, and not let anyone check it for bugs, refer to rule number 10.

The point of the review is to find and fix potential issues, not degrade or humiliate the developer who wrote it. If you feel you must publicly humiliate the developer who wrote the insanely complicated, highly optimized, undocumented inline assembly code that doesn't check its inputs or work the way the customer really wants, in one big patch, refer to rule number 10.

9. Don't Stay Blocked

Sometimes you encounter a tantalizing problem. It's an intricate web that draws you in, challenging you and firing up your brain cells for days.

Yeah. Or you could just ask the guy in the cubicle next door.

Unfortunately, your main goal as a developer on a project is to deliver business value to your customer as quickly and efficiently as possible, not to spend days taking on the personal challenge of unraveling some insanely complicated, highly optimized, undocumented inline assembly code by yourself. You may take it as an insult to your technical kung fu, but it's far better to spend a few minutes asking a guru for help than waste hours gnawing on a problem before working out the answer for yourself.

The flip side of this is that you should share your expertise when someone else is blocked. If you feel don't have time to help out a teammate who needs it, refer to rule number 10.

10. Do Unto Others As You Would Have Them Do Unto You

The most important rule of them all. In fact, all the other rules in this coding convention actually come out of this one.

When you start on a new project, what do you want the code to look like?

  • Do you want it to have a consistent style so you can understand it?
  • Do you want a simple design?
  • Do you want to see familiar APIs?
  • Do you want to see documentation for the code?
  • Do you want it to be secure?
  • Do you want it to be full of bugs?

Write your code with the next guy in mind--the one who will inherit the code and not have you to talk to about it.

You're on a team and everyone on that team must be able to trust and rely on each other. If you do something that jeopardizes that, the whole team suffers. Your teammates must be able to trust you to follow these simple rules so that the whole team can be more agile and efficient.