Even though we all face similar issues in most of our projects, we still lack defined ways of tackling them. Throughout my years in software development, I have used some solutions to the recurring problems that plague most of my development projects, solutions that have really helped me effectively execute projects. In this article, I share with you three best practices for project execution, some of which could be considered full-fledged patterns:
- Use template code
- Write an effective developer's handbook
- Perform automated code review
Use template code
A sample code implementation for a simple and a complex business use-case can help developers write effective and efficient code. Consider the following factors that often plague software development projects:
- Technologies change, and finding competent technical people with experience in new technologies can prove difficult. Plus, newer developers may not have experience writing efficient and effective code. Template code eases the way to learning new technologies and provides an outstanding reference point for developers.
- Learning and implementing new technologies takes time and might lead to a mess if not handled properly. Instead of forcing developers to learn on their own, jump-start them in their development by offering the template code as a reference point they could use for coding.
- Many projects must be completed within tight schedules and with limited manpower. Everybody in a project shouldn't have to reinvent the wheel. Senior technical people might be available at design time, but when it comes to real implementation, developers are usually on their own. Trivial issues can get lost, only to be discovered when they've already caused a mess. How many times do Javadocs follow a standardized format and guidelines? How many times does code follow well-defined idioms and best practices? Visual framing is more effective than books or reference manuals, thus, template code comes to the rescue.
- Many software projects are not only large, but also distributed. Sometimes, projects execute in different parts of the world. When the project is nearing completion, you don't want customers to be surprised by code that doesn't meet their expectations. Send sample code to customers well before construction starts and record their feedback. This sample code should be realistic and representative, not just a "Hello World" kind of application.
- Developers usually have a bulk of reference manuals, standards, and frameworks to help them with a project. But coding idioms may not be obvious even if a design is in place. Visual framing helps. Unless developers have real code examples, they may have slightly different interpretations of the proposed project. One simple item could be implemented in various ways, with none of the suggested approaches exemplifying the best implementation. The sample code could help by implementing specific code idioms.
To write your template code, gather a team of experts (both technical and functional) to identify a simple and a complex case from a problem area of the application to be developed. Have these experts come up with an implementation, or template, based on existing design. Below I list some tips for writing this code:
- The code should contain ready-to-use build and deployment scripts. Otherwise, time will be wasted settling these issues in the construction phase.
- The project's basic directory structure should be ready for developers and can contain libraries for use in the project.
- The template code should follow naming conventions, coding styles, standards, and frameworks that will be used in the project.
- Template code should follow a well-defined Javadoc template (e.g., Eclipse-based) that shows developers how to write Javadocs. Writing good Javadocs is important because, usually, they may be the only documentation available to the existing code's maintenance and enhancement teams.
- Well-defined coding idioms in the programming language should be used in the template code, which could help developers write effective code.
- Template code should define a standard approach for using frameworks. Writing framework-specific implementation classes in a project may be a difficult task to a new developer in the initial construction phase. Sample code can help in understanding these concepts. Even if a lot of documentation is available for a framework, it's not always easy to figure out how to code effectively.
- Template code should also illustrate how to write test cases using JUnit or other testing frameworks.
- To avoid surprises at the very end, the customer's technical team should also review the code so they are more aware of the quality they will receive at the end of the construction phase.
- Template code should cover an end-to-end use-case, i.e., from presentation layer to data layer.
- A full-fledged presentation should be conducted to familiarize developers with the nuances of template code. Developers should understand what needs to be done in each layer and know what coding idioms and best practices have been used, or could be used, and why.
- Developers get a reference to start their coding.
- Customers and developers are on the same page as to the expected quality, thereby avoiding those issues that generally crop up because of misunderstandings.
- Developers have a skeleton on which to start their coding.
- Developers are more at ease with the framework and with any external APIs or components they will use, which enhances productivity.
- Developers don't keep reinventing the wheel. Most of the best practices and coding idioms are on display for them, which again enhances productivity.
Effective developer's handbook
Suppose we must execute a huge project that requires 30 to 50 people on a regular basis. Not all developers are the masters of the technologies and standards they must work on. One single project might include varied technologies and proprietary frameworks that may be used in future Java Enterprise Edition projects. How to transfer that amount of knowledge is a big challenge. It has some caveats attached too:
- Many big projects are in development for a long time period (a year or two). The attrition rate in the software industry is considerably high. Let's accept it. It's a ground reality and challenge too. Recruiting new people may be easy enough, but transferring knowledge is again a big task especially at a time when the project is in a time crunch.
- Some developers may not be at the desired skill level. In today's world, finding skilled developers at the right time is quite difficult. When working within a tight schedule, these new developers won't have the time to brush up on those huge technical books or reference manuals. Some might be sharp and efficient enough to put in the extra time to study and apply those concepts, but that's not a guarantee for all.
- Maintaining a newly built software project is also a big challenge. At the end of a development cycle, the customer's IT team may itself maintain code. For these people, becoming familiar with the technical architecture and applying changes to it might be a big task. Unless we have a defined way of transferring knowledge, the IT team might have a frustrating experience digging into the code and design documents in the initial days.
A developer's handbook should solve the above-mentioned problems. But how do we write an effective one?
Writing a developer's handbook
Here are some tips to writing an effective developer's handbook:
- Handbook should include all related information necessary for setting up a development environment.
- Sentences should be short and easy to read. It's a failure of the writer, not the reader, if the reader finds the handbook difficult to read.
- Handbook should be full of examples. Examples bring out the clarity of what is written.
- Ask a developer unfamiliar with the technologies used in the project to review the handbook. That way, if the book creates confusion or ambiguities, they can be cleared up before others use it.
- Handbook should be ready as a part of the low-level design phase and be available at the beginning of the construction phase.
- How much information should be included in the book? How do you balance between too much information and too little? Developers don't like to read a bulky manual. But, at the same time, the handbook shouldn't lack information that provides scope for many ambiguities. Think about what a developer actually needs, not just about all the information that could be provided. Use a simple, straightforward, step-by-step approach while writing the handbook.
- The handbook should be intuitive and shouldn't distribute information here and there. The text could follow certain steps that a developer follows in real life. For instance, in a Java enterprise project, one would first set up the development environment, then start coding for the presentation layer and the application's data layer. The handbook should follow this flow of steps.
- Make sure the handbook doesn't confuse the developer. For instance, if the developer needs to use specific XDoclet tags while writing Struts action classes, he should be aware of the tags to be used in the project, their meaning, and how to use them. For more details, he can always refer to the reference manual.
Let's think about a real developer's handbook for a Java enterprise project and the details it should include:
- Setup details: When a new developer enters a project, he must set up the environment to start work. Don't assume the developer is aware of the small, or even big, details of a project. For instance, if a project is using the Eclipse-WebLogic combination for creating a Web application, a new developer may not even be aware of Eclipse, or Weblogic for that matter. Thus, this may be the first part of your developer's handbook. Any new developer with basic Java knowledge should be able to easily follow the handbook.
- Presentation layer details: Usually, developers start in the presentation layer while working on a use-case. You should give specific steps in the handbook for creating presentation components. For instance, if a project uses Struts as the presentation framework, defining steps for writing action and form classes should be included. If a project uses XDoclet for creating
struts-config.xmland other Struts configuration files, those steps should be included too. Similar coverage can be given to JSP (JavaServer Pages) also. As per the Model-View-Controller pattern, JSP pages should not contain any Java logic whatsoever. But how to achieve that in a real sense using the JSP Standard Tag Library may be a bigger question for novice or middle-level developers. How to use JSTL in JSP pages with some real examples could also prove helpful.
- Business layer details: Business logic may be written in stateless Enterprise JavaBeans components, Spring-based components, or simple plain-old Java objects. Provide the skeleton of a business component to be used in the project, along with real-life examples.
- Data layer details: Depending on the persistence mechanism the project uses, provide guidelines for writing JDBC (Java Database Connectivity), Hibernate, or any other framework-based DAO (Data Access Object), and then include steps and best practices to be used in the project.
- Miscellaneous details: Provide information about the internal/external components, irrespective of which layer they are used in the J2EE project. You could include logging, an email component, auditing, and security to name a few. Also, in the project's later stages, the handbook may include sections on how to extend some business needs. For instance, if a batch framework is in place, how do we extend it for a new batch?
Automated code review
Code reviews are yet another issue. When code is generated in chunks, continuous code review is needed. Even if you might have defined a set of rules for code review, many issues involved in code review cannot be constrained in rules. Everyone has their own way of reviewing code based on their own expertise and experience. Also, some issues are trivial and cannot be conveyed on a line-by-line basis. Depending on the amount of code one has to review, these trivial issues could get lost somewhere. What if errors are implicit in the IDE itself? Instead of uncovering them manually, some tools can help find these problems.
Eclipse IDE settings
Sometimes, IDE settings help. For instance, you can modify the preferences in the Eclipse IDE to issue warnings in case problems result in the code. Here is an example of the preferences changes in Eclipse for Javadocs.
If you look closer, Eclipse will issue a warning in the IDE itself, which developers can correct. In case project standards are stringent, errors can be issued that force developers to correct problems.
Similarly, a tool called Jlint could be used with Eclipse to find trivial problems in the code. Follow these steps to use it:
- Download the Jlint plug-in and binary, and extract the binary to the C:\lint folder. Also extract the plug-in to the Eclipse plug-in directory.
- Run Eclipse and go to the Windows menu, then Preferences, then Java, then Jlint, and set the Jlint location to C:\jlint\jlint.exe.
- Right-click on your Eclipse project in the Resource view and select Jlint. You will receive yellow warning marks after the workspace builds.
Here is an example of the settings in Eclipse for Jlint.