Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Perl > Perl Misc > new topic: I call length($<string>) and get number of lines - codefrag below - on MAC OS X 10.7

Reply
Thread Tools

new topic: I call length($<string>) and get number of lines - codefrag below - on MAC OS X 10.7

 
 
Tim McDaniel
Guest
Posts: n/a
 
      06-17-2012
Rainer Weikusat <(E-Mail Removed)> wrote:
>Code is not documentation.


A source file
- must express to the compiler the instructions to be followed
- also ideally ought to communicate to a human reader, expressing the
purpose and function of the overall file and of the various parts

I believe that most code, just by being code, communicates its purpose
to humans, at least at the lowest tactical levels and often even
higher. I believe that there is such a thing as "self-documenting
code" -- that code can also be documentation.

For example, a variable doesn't just have a use as a distinct thing,
but its name can be documentation: @cmd, $i, MAX_WIDTH, @global_flags,
$subdirectory. I've sometimes assigned intermediate values in an
expression to appropriately named variables -- sometimes because I
want to see the intermediates during debugging, but sometimes just to
clarify a large computation.

That is, I disagree with the premise of
>Code is not documentation.

I define "documentation" as "everything that communicates to a human
reader". So I say that all code is documentation. Further, since
comments so easily get out of date, code is really the primary
documentation. If you insist that "documentation" must be "everything
explanatory that isn't code", then I think your definition has no
practical use.

When I have more than one way to write code to perform an action,
I consider efficiency, but I also consider a reader of the code
(my future self as well) and how well they will grasp it at a glance.
Where efficiency matters little (a small array, a computation
dominated by a larger process), I might use something easy to
understand. Or I might use something trickier and obscure, but
comment it copiously.

The immediate case was someone writing a line that localized $/ and
also expressed that they wanted it to be undefined. I'm not the one
who expressed the notion that the undefined value is important to
emphasize. Maybe you think that
local $/;
expresses the concept well enough. But I've hit enough problems of
looking at a block of code and trying to figure out what the values
are supposed to be at the end, and enough cases of assignments being
forgotten, that I prefer to be explicit.

--
Tim McDaniel, http://www.velocityreviews.com/forums/(E-Mail Removed)
 
Reply With Quote
 
 
 
 
Rainer Weikusat
Guest
Posts: n/a
 
      06-18-2012
(E-Mail Removed) (Tim McDaniel) writes:
> Rainer Weikusat <(E-Mail Removed)> wrote:
>>Code is not documentation.

>
> A source file
> - must express to the compiler the instructions to be followed
> - also ideally ought to communicate to a human reader, expressing the
> purpose and function of the overall file and of the various parts
>
> I believe that most code, just by being code, communicates its purpose
> to humans, at least at the lowest tactical levels and often even
> higher.


People believe in all kinds of strange stuff. If you wrote the code,
chances are that seeing it reminds you of its purpose. But that's
obviously not going to happen for anyone else and in this case, the
(source) code communicates what the code is doing but not why it is
doing this.

[...]

> The immediate case was someone writing a line that localized $/ and
> also expressed that they wanted it to be undefined. I'm not the one
> who expressed the notion that the undefined value is important to
> emphasize. Maybe you think that
> local $/;
> expresses the concept well enough.


local $/;

is an operation whose semantics are documented: It creates a new
lexical binding for $/ (meaning, one which exists until the (dynamic)
end of the enclosing block) and - as with all Perl variables which
aren't initialized - its initial value is the so-called 'undefined
value'.

> But I've hit enough problems of looking at a block of code and
> trying to figure out what the values are supposed to be at the end,
> and enough cases of assignments being forgotten, that I prefer to be
> explicit.


And I have encountered enough cases were people managed to outsmart
themselves in their own code and made 'trivial oversight' errors
because of that that I'm completely convinced that the overriding
concern when writing code ought to be: Keep it simple. Every
expression in the code is one which somebody who sees it for the first
time has to read and understand, there's always a possibility for
errors here and the more expressions there are, that is, the more
complicated the code is, the greater the chance of such a
misunderstanding becomes. And this implies that one should never, ever
write any code which doesn't have a well-defined technical purpose
someone who doesn't share a brain with the author can understand: Any
such occurence make the code more complicated, by virtue of adding
expressions to it, but since there's nothing tangible in return, this
is a completely useless complication.

Apart from that none of

local $/;

local $/ = undef;

local $/ = undef;
$/ = undef;
$/ = undef;
$/ = undef;

are anyhow more 'explicit' than any of the others. Pointles
repetitions do not serve to make a text clearer.
 
Reply With Quote
 
 
 
 
Tim McDaniel
Guest
Posts: n/a
 
      06-19-2012
In article <(E-Mail Removed) >,
Rainer Weikusat <(E-Mail Removed)> wrote:
>(E-Mail Removed) (Tim McDaniel) writes:
>> Rainer Weikusat <(E-Mail Removed)> wrote:
>>>Code is not documentation.

>>
>> A source file
>> - must express to the compiler the instructions to be followed
>> - also ideally ought to communicate to a human reader, expressing the
>> purpose and function of the overall file and of the various parts
>>
>> I believe that most code, just by being code, communicates its purpose
>> to humans, at least at the lowest tactical levels and often even
>> higher.

>
>People believe in all kinds of strange stuff. If you wrote the code,
>chances are that seeing it reminds you of its purpose. But that's
>obviously not going to happen for anyone else


I *have* to be misreading you. You can't possibly be asserting that
it is impossible for you to deduce meaning and purpose behind these
example lines that I just came up with:

if (! send_email($from, $to, $subject, $body)) { ... }

foreach $i (0 .. @array-1) { ... }

$value =~ s/\s+/ /g;
$value =~ s/^ //;
$value =~ s/ $//;

my @org_ids = SQLvalues('select id from organization where deleted is null');
my @meta_orgs = GetEnclosingOrgs(@org_ids);

{
my %unique_ids;
@unique_ids{@ids} = ();
@ids = sort keys %unique_ids;
}

--
Tim McDaniel, (E-Mail Removed)
 
Reply With Quote
 
Rainer Weikusat
Guest
Posts: n/a
 
      06-19-2012
(E-Mail Removed) (Tim McDaniel) writes:
> In article <(E-Mail Removed) >,
> Rainer Weikusat <(E-Mail Removed)> wrote:
>>(E-Mail Removed) (Tim McDaniel) writes:
>>> Rainer Weikusat <(E-Mail Removed)> wrote:
>>>>Code is not documentation.
>>>
>>> A source file
>>> - must express to the compiler the instructions to be followed
>>> - also ideally ought to communicate to a human reader, expressing the
>>> purpose and function of the overall file and of the various parts
>>>
>>> I believe that most code, just by being code, communicates its purpose
>>> to humans, at least at the lowest tactical levels and often even
>>> higher.

>>
>>People believe in all kinds of strange stuff. If you wrote the code,
>>chances are that seeing it reminds you of its purpose. But that's
>>obviously not going to happen for anyone else

>
> I *have* to be misreading you.


The verb is misquoting not misreading.
 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Browser crashes with below code.What is wrong in below code. kiran Javascript 12 12-07-2011 02:38 PM
Hard or Easy? To find string, then grab criterion matched lines above and below? samiam@mytrashmail.com Perl Misc 13 10-09-2006 07:56 PM
Could someone scan me a picture of the below? (Read Below) starlightvoyager@yahoo.com DVD Video 1 08-28-2006 05:42 AM
grepping lines above and below a pattern found mike Perl Misc 15 05-21-2004 08:46 AM
Re: how to read 10 lines from a 200 lines file and write to a new file?? Joe Wright C Programming 0 07-27-2003 08:50 PM



Advertisments