Beefy Boxes and Bandwidth Generously Provided by pair Networks
Pathologically Eclectic Rubbish Lister

Re: What is code readability?

by Herkum (Parson)
on Jan 02, 2007 at 23:39 UTC ( #592667=note: print w/replies, xml ) Need Help??

in reply to What is code readability?

I think one of the most important concepts to take from programming is replacing abstract code with a function name that describe the work it is supposed to do. For example, I came across this code,

$fee = ($tfee / 100 + $sfee/100 + 0.0000001) * 100 $mfee = 200 if ($fee >= 100); $fee = $mfee if $mfee;

I don't even know what this does or why it is doing it. If they had done something like this, I would have a basic understanding of the what they are trying to accomplish.

$fee = determine_maximum_fee(); sub determine_maximum_fee { $fee = ($tfee / 100 + $sfee/100 + 0.0000001) * 100 $mfee = 200 if ($fee >= 100); $fee = $mfee if $mfee; return $fee; }

To me, the difference between a good developer and a bad developer is being able to break code into functions that explain what the program is supposed to be doing. Something most beginning programmers do not understand.

Update: Changed sub determine_total_fee to sub determine_maximum_fee(), thanks to the Anonymous Monk for pointing out the error

Replies are listed 'Best First'.
Re^2: What is code readability?
by Anonymous Monk on Jan 03, 2007 at 04:13 UTC
    $fee = determine_maximum_fee(); sub determine_total_fee {
    Refactoring error? Is it determine_maximum_fee() or determine_total_fee? And that name that is overly verbose.
    $fee = ($tfee / 100 + $sfee/100 + 0.0000001) * 100
    ...what in the world is this doing? If I had to guess, I'd say it is a hack to misuse floating point numbers, instead of using something like Math::Currency, although I'd expect to see some calls to int(). And it diddles with global variable $foo.
    $mfee = 200 if ($fee >= 100);
    ...refers to global variables $mfee and $fee. And $mfee is non-descript. And we should at least have a comment explaining the magic numbers 100 and 200.
    $fee = $mfee if $mfee;
    ...this is seems like it is probably a horrible hack to avoid warnings about undef.
    return $fee; }
    I'd probably not refactor into a subroutine, instead using a proper data type and something like...
    use constant BREAK_POINT => 100; use constant BONUS_FEE => 200; my $total_fee = $tfee+$rfee >= BREAK_POINT ? BONUS_FEE : $tfee+$rfee;

      You do bring up some good points about the code, however the problem is not with the code or its execution but its context. By moving the code into a function it should help declare a context of what is going to happen even if it hides what it is exactly doing.

        Maybe you should post what you think the real subroutine should look like. I suspect that the code is not being used more than once, there by negating the biggest incentive to turn it into a separate procedure. By the time you rewrite it properly, (by removing references to global variables, passing in parameters, etc.), it'll be longer and harder to understand. I'll go out on a limb here and say all the context you need is provided by an appropriate variable name, like $total_fee, for instance. But there's a chance that we'll just have to agree to disagree.
Re^2: What is code readability?
by Moron (Curate) on Apr 17, 2007 at 18:03 UTC
    I don't see your sentiment (which I agreed with) reflected in your modifications to the example. To my mind, breaking it into understandable functions would end up more like:
    # with this level of modularity almost anything is readable! sub determine_maximum_fee { # # functional description goes here # $fee = Roundup( Sum( @_ ) ); $fee < 100 ? $fee : 200; # all 100+ fees become 200 } sub Roundup { # # Increase just barely to avoid any rounding down problem # 100 * ( ($_[0]/100) + 0.0000001 ); } sub Sum { # # needs no description. # my $result=0; $result += shift() || return $result while (1); }

    ^M Free your mind!

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://592667]
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others cooling their heels in the Monastery: (6)
As of 2020-07-12 09:48 GMT
Find Nodes?
    Voting Booth?

    No recent polls found