Self Doc

This page was migrated from a javaranch.com.jsp


   
   
     
     Java Programming Style Guide
   
 





4 - Commenting

4 - Self Documenting Code

<em>"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." </em>

 

   

     --- Martin Fowler, Refactoring: Improving the Design of Existing Code
   

 

Rather than trying to document how you perform a complex algorithm, try to make the
algorithm easier to read by introducing more identifiers. This helps in the future if the
algorithm changes and the documentation does not.

Original:

   /** determine if the given year is a leap year.<p>        The Gregorian calendar principal states that a leap year occurs        every fourth year, except every 100 years, except every 400        years.<p>        If the year is evenly divisible by 400 or is evenly divisible by        4 and not by 100, then it is a leap year.<p>        @param year The year to be tested.  Make sure this is a four digit year!<p>        @return true if "year" is a leap year.<p>    */    boolean isLeapYear( int year )    {        return ( ( y % 400 == 0 ) || ( ( y % 4 == 0 ) && ( y % 100 != 0 ) ) );    }

Modified:

   /** determine if the given year is a leap year.<p>        The Gregorian calendar principal states that a leap year occurs        every fourth year, except every 100 years, except every 400        years.<p>        @param year The year to be tested.  Make sure this is a four digit year!<p>        @return true if "year" is a leap year.<p>    */    boolean isLeapYear( int year )    {        boolean y4 = ( year % 4 == 0 ) ;        boolean y100 = ( year % 100 == 0 ) ;        boolean y400 = ( year % 400 == 0 ) ;        return ( y400 || ( y4 && ! y100 ) );    }

Or:

   /** determine if the given year is a leap year.<p>        The Gregorian calendar principal states that a leap year occurs        every fourth year, except every 100 years, except every 400        years.<p>        @param year The year to be tested.  Make sure this is a four digit year!<p>        @return true if "year" is a leap year.<p>    */    boolean isLeapYear( int year )    {        boolean returnVal = false ;        if ( year % 400 == 0 )        {            // this is definitely a leap year            returnVal = true ;        }        else if ( year % 4 == 0 )        {            // this is probably a leap year            if ( year % 100 == 0 )            {                // this is definitely not a leap year                // do nothing            }            else            {                // this is definitely a leap year                returnVal = true ;            }        }        return returnVal ;    }