Agile FAQs
  About   Slides   Home  

 
Managed Chaos
Naresh Jain's Random Thoughts on Software Development and Adventure Sports
     
`
 
RSS Feed
Recent Thoughts
Tags
Recent Comments

Self Documenting Code Example

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.

1
2
3
4
5
6
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:

1
2
3
4
5
6
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 the session is renewed.

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:

1
2
3
4
5
6
7
8
9
10
11
12
/**
* 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.

1
2
3
4
5
6
7
8
9
10
11
private HttpSession renewSession(HttpServletRequest request, HttpServletResponse response)
{
  HttpSession unauthenticatedSession = webUtils.getSession(request, response);
  invalidateSessionToEliminateSesionFixation(unauthenticatedSession);
  return webUtils.getSession(request, response);
}
 
private HttpSession invalidateSessionToEliminateSesionFixation(HttpSession session)
{
  session.invalidate();
}

OR

1
2
3
4
5
6
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, its comments and also making sure they are in sync.

  • John Coleman

    This is definitely arguable and I’d argue that it’s an ugly refactoring.

    After the refactoring it appears you have written a bunch of convenience methods that do nothing but delegate, and given their names I would assume they are useless for anything else. All this code appears to do is, surprise, renew the session. The authentication really happens in the createAuthenticatedSessionUsingAuthenticatedEntity(…) method. Your renewSession(…) method does not appear to carry any information about authentication; stating that it does by the method names, as in your refactoring, is misleading.

    Your colleague’s first thought was correct. Code should tell you what it does, comments should provide the why. The “why” in this case absolutely belongs in a JavaDoc and not in the method names. Just because you “hate JavaDocs” does not make them less of a standard – most developers are going to go there first and not read the code, especially if you are releasing an API.

  • John Coleman

    This is definitely arguable and I’d argue that it’s an ugly refactoring.

    After the refactoring it appears you have written a bunch of convenience methods that do nothing but delegate, and given their names I would assume they are useless for anything else. All this code appears to do is, surprise, renew the session. The authentication really happens in the createAuthenticatedSessionUsingAuthenticatedEntity(…) method. Your renewSession(…) method does not appear to carry any information about authentication; stating that it does by the method names, as in your refactoring, is misleading.

    Your colleague’s first thought was correct. Code should tell you what it does, comments should provide the why. The “why” in this case absolutely belongs in a JavaDoc and not in the method names. Just because you “hate JavaDocs” does not make them less of a standard – most developers are going to go there first and not read the code, especially if you are releasing an API.

  • http://www.andhapp.com/ andhapp

    @John:
    I am not taking sides in the comparison of Javadocs and commenting codes… but have you read Clean Code by Robert Martin. If not, then please do so.

    It does not matter if you are releasing your code as an API or not…code must be maintainable and easier for the new developers to pick up.

  • http://www.andhapp.com andhapp

    @John:
    I am not taking sides in the comparison of Javadocs and commenting codes… but have you read Clean Code by Robert Martin. If not, then please do so.

    It does not matter if you are releasing your code as an API or not…code must be maintainable and easier for the new developers to pick up.

  • http://www.andhapp.com/ andhapp

    This site does not work properly in Firefox…the code is all over the place.

  • http://www.andhapp.com andhapp

    This site does not work properly in Firefox…the code is all over the place.

  • barcode generator

     Nice Information! I personally really appreciate your article. This is a great website. I will make sure that I stop back again!.
    barcode generator

  • aser

     I think eliminateSesionFixation should be enough as a method name..


    Licensed under
Creative Commons License