Terrible Code

request.setParameter("qualifySkus", getSkusRepository(d, cItem));
  1. “qualifySkus” is confusing. Is it an array/list/collection of “qualifiedSKUs” or a flag that’s a result of “qualifyingSkus” or….
  2. “qualifySKus” should be a constant with a nice comment, not an in-line String.
  3. The method getSkusRespository seems like it would return a catalog repository, doesn’t it? Instead it takes in a List of String SkuIds, loads up the corresponding SKU RepositoryItems, removes any that have the property “isLive” set to false, and removes any that have a current inventory stock level of zero. It then returns an ArrayList of those filtered SKU RepositoryItems. Perhaps a better name might be “getLiveInStockSKUs”?
  4. What on earth is “d”? Even looking at the full code of this class, it’s very difficult to tell what d is meant to contain. It’s actually a List of Strings of SkuIds that are qualifying skus for a given promo. “qualifiedSkus” would be a better name.
  5. cItem is a commerce item. However it’s not actually used by the getSkusRepository method at all. There’s no reason to pass it in.
  6. This line is in an ATG droplet and shoves the result of the getSkusRepository method into a request param before servicing an oparam. However, as you can see, it doesn’t inspect the output of the method. As I explained above, the method actually filters a list of SKUs based on isLive and current inventory state. It’s very possible that there will be no live and in-stock SKUs, and the param’s value will be null or an empty list. In that case, we’d actually want to render a different oparam, which is defined and called elsewhere, but not here. Validate your output!

That’s six issues in one line. Please don’t write code like this.

Project Roles – ATG Development Practices

Let’s define some roles for a full life-cycle ATG Development effort. Your company may not be arranged exactly like this, but it’s a good baseline I think.

Client Representative
The single face of the client. The sole conduit to and from the client.

Project Manager/Dev Manager
The owner of the schedule, resources, project status, and interface between the project team and the rest of the company. The solver of problems, overcomer of obstacles.

Architect
ATG Architect. Responsible for application design and quality. Provides ATG knowledge and guidance to the team throughout the entire project lifecycle. Provides mentorship, documentation, and more.

Business Analyst
Responsible for documenting the business requirements and involved in the process of translating the business requirements to technical requirements and test scripts.

Tech Lead
Leader of the technical implementation team. Responsible for code quality, task distribution, and mentorship. Point person for reporting on development status

Tech Team
Team of JSP and Java developers. Responsible for the ATG implementation.

Creative Lead
Leader of the creative team. Point person for creative issues and direction.

Creative Team
Team of designers, and front end (html/css) developers.

Test Lead
Leader of the test team. Point person for ensuring test plans are created, and reporting on test pass status.

Test Team
Team of testers.

—- edit: added on 5/23/08 ——
DBA
Database Administrator to manage the database instances, and review SQL and table structures.

What do you think? What would you add or change?

Starting Assumptions – ATG Development Practices

We need to start with some basic assumptions to guide our solution.

Here is my initial list:

  1. The applications being built will be important commerce or personalization sites, but will not be the sort of critical applications like nuclear plant software or air traffic controlling programs which require massive testing and documentation
  2. The team may be geographically distributed
  3. Time, Budget, Functionality, and Quality are all important, but we recognize the inherent truth of the saying: “you can have it: fast, cheap, good. pick two.”
  4. The application should be considered as being built for an external client. This may be because you work as an implementor, or simply that the “client” is your company’s business team
  5. You should be able to be proud of what you’ve build, the code, the look, all of it
  6. You should be delivering something of value to the client, ideally something with measurable value
  7. You need to be as flexible as you can regarding changes, without impacting the delivery quality of date
  8. The process should be well documented, repeatable, etc…
  9. Communication is king
  10. We can always improve

ATG Development Practices

In a series of blog postings, and hopefully with substantial input from the ATG community, I am going to try to define ATG development best practices. From how to run a development project, to coding standards, and more. I know it will be impossible to make a perfect set of practices for everyone, there is no one size fits all, but based on some basic assumptions, I will strive for a great starting point, instead of a perfect solution.

It will take time, but will be well worth it in the end.

This practice definition will be focused on delivering the highest quality ATG applications, on time, and on budget, while maximizing flexibility to accommodate the client’s changing needs.

More specifically the process needs to:

  • Ensure there is a fixed baseline of requirements to build against
  • Allow for accurate estimates, resourcing, budgeting, and scheduling
  • Leverage ATG expertise at many steps of the process, including strategy, requirements gathering, and creative concepts in order to maximize the benefit of the platform and minimize development pain (defined as time/cost/stress/quality-impact)
  • Support a geographically diverse team
  • Define the steps, flow, entrance and exit criteria, and roles for the process
  • Minimize time waste
  • Maximize communication and documentation
  • Be supported by a set of tools and practices to effectively enable the process
  • Deliver high quality (low defect) applications, on time and on budget

And here are the things I will try to address:

  • Project Roles
  • Project Process
  • Development Process
  • Change Request Process
  • Toolset to Support the Processes
  • Hardware, Environments, Software
  • Coding Standards and Best Practices
  • Bug Severity Guidelines
  • Test Phase Exit Criteria
  • Source Code Tagging and Branching Strategy and Naming Conventions
  • Versioning and Build Number Conventions and Tracking
  • Project Naming Conventions
  • Documentation Templates and Conventions