Robert W and the rest of the peons in the COGS application group didn't have their own Architecture Team. Their break room wasn't stocked with an endless supply of snacks. In fact, they didn't even have the budget for quarterly "developer retreats". All they had was a CVS repository, a few servers, and a dedication to their client, the COGS group.

For years, everything ran smoothly: they delivered in full, on time, and had a very satisfied client. That is, until the elite developers from Central IT got wind of their rinky dink operation. After a week-long assessment, they determined that Robert’s team had a number of “serious trouble points”, the worst of which was JavaDoc compliance. Apparently, only 53.8% of their code was fully and properly documented.

"But not to worry," the consultant from Central IT assured them, "we've developed a number of tools and technology that will address the trouble points and ensure your development runs smoothly. Most importantly, we'll get you set up with The Documentor."

The Documentor, as it turned out, was a custom CVS commit hook that would automatically add JavaDoc to any method definitions lacking them. So, checking in this...

public int calculateExpiryScale(String keyCode)
   throws KeyCodeInvalidException {

    ... snip ...

}

... would turn into this...

  /**
   * DOCUMENT ME!
   * 
   * @param foo DOCUMENT ME!
   * @return DOCUMENT ME! 
   * @throws KeyCodeInvalidException DOCUMENT ME!
   */
public int calculateExpiryScale(String keyCode)
   throws KeyCodeInvalidException {

    ... snip ...

}

This was the only documentation required by Central IT.

[Advertisement] BuildMaster allows you to create a self-service release management platform that allows different teams to manage their applications. Explore how!