|
Documented coding conventions take the pain out of development
September 20, 2006
URL:http://www.drdobbs.com/architecture-and-design/coding-conventions-make-them-agile/193003844
Jason Mawdsley is a project leader and Certified ScrumMaster at Macadamian Technologies. You can reach him at [email protected].
Quick--where's your coding convention document? What do you mean you don't know?
If you're like most developers, the coding convention document you were given when you started your job is in the bottom of a drawer somewhere or gathering dust on that top shelf, out of reach. Coding conventions are supposed to be useful tools for creating high quality code, but because they are rarely written by the developers themselves, coding conventions are often viewed as handcuffs shackling developer style and creativity.
This doesn't even take into account developers who work on multiple projects. Or do consulting work. If you do, you can find yourself having to learn different coding conventions several times a year.
In Managing Agile Projects, Sanjiv Augustine says:
Living systems such as projects are complex in that they consist of a great many autonomous agents interacting with each other in many ways. The interaction of individual agents is governed by simple, localized rules and characterized by constant feedback. Collective behavior is characterized by an overlaying order, self-organization, and a collective intelligence so unified that the group cannot be described as merely the sum of its parts. Complex order, known as emergent order arises from the system itself, rather than an external dominating force. These self organizing Complex Adaptive Systems (CAS) are adaptive in that they react differently under different circumstances and co-evolve with their environment.
Development teams are a perfect example of a Complex Adaptive System. They're made up of technical, creative, highly intelligent, and autonomous developers interacting with each other in many ways.
No wonder developers react badly to coding conventions, especially when they are imposed from higher up the food chain or are leftovers from a previous project. This kind of coding convention:
For it to be useful to a development team that matches the Complex Adaptive System criteria, a coding convention will have to consist of rules that are:
With these rules, emergent order comes from the team itself, rather then an external dominating force like a coding convention. These CASs are adaptive in that they react differently to different situations and environments, and evolve over the life of the project.
Simple rules let your team deliver high-quality code as efficiently as possible. With this in mind, my agile coding convention consists of these simple rules:
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.
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.
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.
If you feel you must implement that overly complicated, but clever, linked list that saves 0.02% memory usage, refer to rule number 10.
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.
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.
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.
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.
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.
************************************************
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.
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.
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?
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.
You'll notice that these 10 items have nothing to do with bracketing styles, nor is there a single mention of goto in this entire document. This is because you have to trust your team's ability to make sound decisions, and for the coding conventions to apply a light touch. You can't sweat the small stuff, like having/not having a space between an if and its corresponding parenthesis. After all, the developers all have their own particular coding preferences and you'll needlessly spend an enormous amount of effort trying to change them.
Instead, concentrate on creating an agile coding convention that meets the needs of your agile organization.
Terms of Service | Privacy Statement | Copyright © 2024 UBM Tech, All rights reserved.