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

Re^5: An Introduction to Literate Programming with perlWEB

by holli (Monsignor)
on Jan 13, 2009 at 18:58 UTC ( #736043=note: print w/replies, xml ) Need Help??


in reply to Re^4: An Introduction to Literate Programming with perlWEB
in thread An Introduction to Literate Programming with perlWEB

I disagree. A bug is bug because it creates an unexpected behaviour which differs from the documentation. Once fixed there should be no reason to touch the docs. Of course it can also be the other way round, the documentation is outdated because of a "urgent feature" got implemented.


holli, /regexed monk/

Replies are listed 'Best First'.
Re^6: An Introduction to Literate Programming with perlWEB
by JavaFan (Canon) on Jan 13, 2009 at 20:39 UTC
    A bug is bug because it creates an unexpected behaviour which differs from the documentation.
    Sillyness.

    Suppose you have a routine like this in your company's application.

    # Calculate the average by adding the parameters and # dividing them by the number of elements. sub avg { my $sum = 0; $sum += $_ for @_; return $sum / @_; }
    Now someone files a bug report, the application dies with a divide by zero error, and the line number the bug happens is in this subroutine.

    Now, you think you get high marks on your end-of-the-year review if you close this report with "Not a bug, the behaviour of the routine matches its documentation"?

    Of course, there are many bugs because the code differs from the documentation. But bugs don't disappear just because the documentation matches the code.

    Now, if you had said "you cannot have a bug if the code matches the specification", you may have something to argue (but even that is something I don't agree with).

      That's just an example of a missing edge case. Even when fixed, the original documentation is still valid and does not need to be altered in any way.


      holli, /regexed monk/
        # Calculate the length of a segment by taking the square root of the # differences of the squares of the sum of the x and y coordinates sub segment_length { my ($p1, $p2) = @_; sqrt(($p1->{x} + $p2->{x})**2 - ($p1->{y} + $p2->{y})**2) }
        Bug 715: segment_length doesn't calculate the length of segments correctly. Bug 715 closed by holli: Not a bug, subroutine work as I documented it.
        # Return a random integer 1 .. 6 to simulate a die roll. # Seed the random number generator with the current time before calcul +ating. sub roll { srand(time); 1 + int rand 6; }
        Bug 4519: Due to a seeding the random number generator each time, 'roll' isn't producing random results. Bug 4519 closed by holli: Not a bug. I documented the fact it's seeding the random number generator each time.
        # CSS file span.important {color: green} # Green stands out!
        Bug 20123: important text should be red. Bug 20123 closed by holli: Not a bug, I documented it to be green.
        my $code = $cgi->param("sql_query"); $dbh->do($code); # This is dangerous.
        Bug 40385: All the tables have been dropped!. Bug 40385 closed by holli: I documented that it is dangerous, so it's not a bug.

        But I guess they are all edge cases as well?

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://736043]
help
Chatterbox?
[shmem]: tell them
[Discipulus]: nettop I have some spare time..
[Discipulus]: do you have some spare money? ;=)

How do I use this? | Other CB clients
Other Users?
Others studying the Monastery: (7)
As of 2018-04-20 17:28 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    Notices?