Agile FAQs
  About   Past Conferences   Training   Home  

 
Managed Chaos
Naresh Jain’s Random Thoughts on Software Development and Adventure Sports
     
`
 
Microblog Feed
    Previous Feeds...
    Recent Thoughts
    Comments
    Tags
    Blogroll
    Categories
    Archives
    November 2008
    M T W T F S S
    « Oct   Dec »
     12
    3456789
    10111213141516
    17181920212223
    24252627282930
    RSS Feed
    Add to Technorati Favorites

    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.

    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.

    [Post to Twitter] Tweet This Post  [Post to Plurk] Plurk This Post  [Post to Yahoo Buzz] Buzz This Post  [Post to Delicious] Delicious This Post  [Post to Digg] Digg This Post  [Post to Ping.fm] Ping This Post  [Post to Reddit] Reddit This Post  [Post to StumbleUpon] Stumble This Post 

    • Share/Save/Bookmark

    3 Responses to “Self Documenting Code Example”

    1. John Coleman Says:

      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.

    2. andhapp Says:

      @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.

    3. andhapp Says:

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

    Leave a Reply


        Licensed under
    Creative Commons License
    Design by vikivix