From: Ryan Davis <ryand-ruby@...>
Date: 2010-12-31T17:36:08+09:00
Subject: Re: Parsing the Ruby File


On Dec 31, 2010, at 00:16 , Thillai S. wrote:

> If there are 40 lines of code in the function, then it should have 
> minimum 20 lines of comments for that function.

you're kidding right? quality (of _any_ kind) can _not_ be determined by the ratio of comment to code.

For example (from your own example):

> #
> # Function name : get_days_in_hash
> # Argument :
> # no arguments
> # Return value :
> # days information in hash format.
> # Description :
> # get the days. Assigned value for each day.
> # 1 => 'Mon' ,
> # 2 => 'Tues' ,
> # 3 => 'Wed' ,
> # 4 => 'Thu' ,
> # 5 => 'Fri' ,
> # 6 => 'Sat' ,
> # 7 => 'Sun' ,
> # 8 => 'Leave' ,
> # 9 => 'Holiday'
> # Logical flow :
> # generate the hash
> #
> def get_days_in_hash
> { 1 => 'Mon' , 2 => 'Tues' , 3 => 'Wed' , 4 => 'Thu' , 5 => 'Fri' , 6 =>
> 'Sat' , 7 => 'Sun' , 8 => 'Leave' , 9 => 'Holiday' }
> end

That apparently has GREAT quality as the ratio is 20:3 (depending on how you count it)... That's much much much better than the 1:2 ratio you're setting as your bar, right? Right??

So, by that same logic, the following would be 20:13, that's down to ~3/2, not nearly as good:

> #
> # Function name : get_days_in_hash
> # Argument :
> # no arguments
> # Return value :
> # days information in hash format.
> # Description :
> # get the days. Assigned value for each day.
> # 1 => 'Mon' ,
> # 2 => 'Tues' ,
> # 3 => 'Wed' ,
> # 4 => 'Thu' ,
> # 5 => 'Fri' ,
> # 6 => 'Sat' ,
> # 7 => 'Sun' ,
> # 8 => 'Leave' ,
> # 9 => 'Holiday'
> # Logical flow :
> # generate the hash
> #
> def get_days_in_hash
>   {
>     1 => 'Mon',
>     2 => 'Tues',
>     3 => 'Wed',
>     4 => 'Thu',
>     5 => 'Fri',
>     6 => 'Sat',
>     7 => 'Sun',
>     8 => 'Leave',
>     9 => 'Holiday',
>   }
> end

But it's the same exact code!

Now let's look at your actual comment block:

#
# Function name : get_days_in_hash              # we already know it.
# Argument :                                    # we already know it.
# no arguments
# Return value :                                # described in name
# days information in hash format.
# Description :
# get the days. Assigned value for each day.    # also described in name
# 1 => 'Mon' ,                                  # EXACT DUPE OF CODE
# 2 => 'Tues' ,
# 3 => 'Wed' ,
# 4 => 'Thu' ,
# 5 => 'Fri' ,
# 6 => 'Sat' ,
# 7 => 'Sun' ,
# 8 => 'Leave' ,
# 9 => 'Holiday'
# Logical flow :
# generate the hash                             # no clue what this is for
#

I'd have written the comment as:

##
# Returns a hash mapping the day code (including leave and holiday) to its name.

That drops me from 20:13 to 2:13. That makes mine bad, right?

Before I knew what you were trying to do, I would have probably recommended looking at ruby_parser to figure out your line number problem. But now that I know, I wouldn't. It has like... almost NO comments:

Classes:      12 (    9 undocumented)
Constants:    29 (   28 undocumented)
Modules:       0 (    0 undocumented)
Methods:     466 (  417 undocumented)

and lots and lots of code:

% find lib -type f | xargs wc -l
     120 lib/gauntlet_rubyparser.rb
    1307 lib/ruby_lexer.rb
    1790 lib/ruby_parser.y
    1030 lib/ruby_parser_extras.rb
    4247 total