Agile India.

Yesterday a colleague @ Directi was writing some code and was very unhappy about the code. He was not sure how to write the following method without having to add a comment to explain the rationale behind the code’s logic.

private HttpSession renewSession (HttpServletRequest request, HttpServletResponse response)
{
  HttpSession session = webUtils.getSession(request, response);
  session.invalidate();
  return webUtils.getSession(request, response);
}

The method name expressed what the code was doing (renewing an existing session) but the “why” it was doing what it was doing was missing. The why is very important for someone to understand. This method was invoked from the following method:

void createAuthenticatedSessionUsingAuthenticatedEntity (HttpServletRequest request, HttpServletResponse response)
{
  HttpSession session = renewSession(request, response);
  AuthenticationInfoBean authInfoBean = authUtils.getAuthInfoBean (request);
  session.setAttribute(getAuthenticatedUserBeanKey(), authenticatedBeanCreator.create(authInfoBean.getUsername(), authUtils.getValidatedEntity(request)));
}

One option was to rename renewSession method to renewUnAuthenticatedSessionToEliminateSesionFixationByInvalidatingSession. But in the context where this method was used, it would be too much noise. Not always I’m interested in how and why are you renewing the session.

Another option is to write a JavaDoc for the renewSession method. Personally I hate JavaDocs and I was interested to find a way to eliminate that. So I asked the developer to first write the JavaDoc to express what he wanted to express. He wrote:

/**
* This method retrieves the unauthenticated session, then invalidates the session to eliminate session fixation issue and creates a new authenticated session.
* @param request HttpServletRequest
* @param response HttpServletResponse
* @return HttpSession Authenticated Session.
*/
private HttpSession renewSession (HttpServletRequest request, HttpServletResponse response)
{
  HttpSession session = webUtils.getSession(request, response);
  session.invalidate();
  return webUtils.getSession(request, response);
}

Now looking at the comment it was easy for me to figure out how to write the code such that the comment is not required. This is what we ended up creating.

private HttpSession renewSession(HttpServletRequest request, HttpServletResponse response)
{
  HttpSession session = retrieveUnAuthenticatedSession (request, response);
  eliminateSesionFixationByInvalidatingSession (session);
  return newlyCreatedAuthenticatedSession (request, response);
}

Again its arguable if writing code this way is much better that writing a small JavaDoc comment. As a rule of thumb, I always prefer self-documenting code over code which needs comments to support it. The real problem comes from the fact the comments soon fall out of place with the code. And why spend all the extra time maintaining code and its comments and make sure they are in sync.

Tweet This Post  Plurk This Post  Buzz This Post  Delicious This Post  Digg This Post  Ping This Post  Reddit This Post  Stumble This Post 

This entry was posted on Saturday, November 8th, 2008 at 4:05 pm and is filed under Agile, Design. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.