There are a few themes that recur frequently when discussing software development projects. Money, quality, budget, performance, expense, maintenance, cost…. Okay, some themes recur more often than others. In fact, cost is both the key driver and largest obstacle to project success. Although most people agree that code quality processes reduce the cost of software development and maintenance, these processes are usually the first to be scaled back when deadlines begin to loom and progress is almost invariably less than originally planned. Even though I can go on and on about the cause of these plan versus reality deltas (and I have in the past), today I’ll focus on how you can best survive the reduction in time available to review code by making code easier to review.
Consistent Formatting is the Key to Code Quality
The average developer will tell you that formatting has nothing to do with quality. Of course, you are an above-average developer because you are reading articles on Developer.com rather than looking for three-sentence solutions in a blog entry by someone with no verifiable expertise.
Formatting is critical to quality in two main areas. The first is the ability to review code quickly. Consistent formatting allows a code reviewer to quickly skim through code they have never seen before. Anomalies jump out to the practiced eye much faster if the distraction of inconsistent use of white space, brackets, and alignment are removed from the process.
The second area where standardization of code formatting improves quality is when different developers must work on the same class. Whether it is part of an Agile process of parallel development or because one member has left the team, standard formatting makes it very easy for one developer to read another developer’s code and instantly follow what the code is doing. It also makes it simpler to write better-performing code because consistent formatting greatly reduces the likelihood of creating redundant objects or managing object lifecycles poorly.
Setting and Sharing Formatting Standards
For Java (the only language I will cover here), formatting preferences can be found under WindowPreferences to access the Preferences dialog, and then JavaCode StyleFormatter. Here you will find some common formatting standards pre-installed.
Figure 1: Pre-Installed Formatting Options
If your team happens to follow any of these standards as-is, all you need to do is communicate to your team which one to choose. You also can share the preferred pre-installed option through Preferences; this will be covered in the next section.
Although I can live with these if they are accepted by a team as the standard, I have my own personal preferences I prefer to use when I am the one making the choice, so I usually go to the next step, which is to create my own formatting profile.
Figure 2: Custom Profile Dialog
The custom profile will be based off of an existing profile. Once you have a custom profile, you can extend it by creating a new profile based on your custom profile if you want. Having created your profile, you will be sent to the Edit screen (accessible in the future from the Edit button shown in Figure 1). My personal preference pet-peeve is conveniently the first setting available, which is the tab policy.
Figure 3: Formatting Profile Editing Screen
The menus are very intuitive, so if you already have coding standards written you should be able to configure the profile in less than an hour. Of course, if you don’t, now is the perfect time to establish them. When you have completed each section, click Apply to save it to your profile.
Once your profile is completed, many aspects will take immediate effect, such as the formatting of braces when using wizard-generated code such as getters and setters. Other options, such as Align fields in columns, require using the SourceFormat option from the menu.
Figure 4: SourceFormat Option
This option can also be used on code written before the creation of the profile to quickly format using your profile.
Figure 5: Before: Old, Unformatted Code
Figure 6: After: Standardized Formatting in an Instant
Once you have your formatting profile defined, you can export it from the Formatter Edit menu.
Figure 7: Exporting Custom Format Profile
This XML file can be imported into a team member’s installations from the initial Formatter dialog screen. For the curious, below is an example of the exported XML (which can be edited by hand for those who prefer that approach):
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <profiles version="11"> <profile kind="CodeFormatterProfile" name="Scott" version="11"> <setting id="org.eclipse.jdt.core.formatter. comment.insert_new_line_before_root_tags" value="insert"/> <setting id="org.eclipse.jdt.core.formatter. insert_space_after_comma_in_annotation" value="insert"/> <setting id="org.eclipse.jdt.core.formatter. insert_space_before_comma_in_type_parameters" value="do not insert"/>
Preferences Add More Standards for Less Confusion
A Formatter profile can (and probably should) be maintained at an enterprise level. At a project level, there are many other Eclipse configurations that can be standardized for a smoother development process.
You may have noticed when navigating to the Formatter preferences (refer to Figure 1) that there are several additional options available under the Code Style section. I think one of the most advantageous options are the Code Templates, which are used when generating new code. The dialogs provide the use of built-in variables making for easy configuration.
Figure 8: Adding Variables to Templates Made Easy
At a more project-specific level, classpath variables are handy for consistent references to legacy libraries. These can be set under the Build Path preference.
Figure 9: Classpath Variables
Unlike the Formatter options, these other options do not have a single export. Instead, they can be shared as a group by exporting preferences. When using preferences, you do not need to export your Formatter profile separately; it will be included in the exported preferences.
The preferences export, being at a more global level, is accessed from the global FileExport command.
Figure 10: Exporting Preferences
You may want to edit the exported file for localized paths to common variables, such as the JRE location:
The above line should be removed because every installation will have a JRE path and it can be annoying to have run-time errors dues to an invalid path. Alternatively, you could have standards for installation paths, and not need change these.
Localized paths for classpath variables should be preserved even if they will cause compile-time errors. These errors are easily identified in the Problems panel. Once located at a project level, the next step is to go to the project preferences dialog, locate the clearly marked error under the Build Path panel, and edit the value to match your local installation. Because the original path and file name are part of the invalid path, it should make it much easier to find the correct path in your local environment. Obviously, this approach requires that preferences be shared only once through the import process.
Almost every technical lead wants to maintain code quality and is frequently frustrated by tightening timelines to have the time to enforce code quality as part of the mentoring process. By using Eclipse preferences as part of a standard developer set, the reduced time available for code review can be put to better use by making the code easier to read, thus faster to review. Sharing Eclipse preferences also makes it easier to on-board new developers to a project.
About the Author
Scott Nelson is an optimization consultant with over 10 years of experience designing, developing, and maintaining web-based applications for manufacturing, pharmaceutical, financial services, non-profit organizations, and real estate agencies for use by employees, customers, vendors, franchisees, executive management, and others who use a browser. For information on how he can help with your web applications, please visit http://www.fywservices.com/ He also blogs all of the humorous emails forwarded to him at Frequently Unasked Questions.