Subject: How to write legible perl code: Summary

From: Shlomi Fish <[email-masked]>
Date: Wed, 8 Aug 2001 14:54:40 +0300 (EEST)

I am preparing an essay entitle "How to write legible perl code". The
essay is not written yet, but I have the summary ready. Please read it and
comment, or add some extra advice of your own (don't worry - you will be
credited).

Regards,

	Shlomi Fish

<<<<< Summary starts here >>>>>

Forward:
--------

* Perl was designed so that quick and dirty code could be easily written.

* If, however, the code needs to be maintainable, some common perl practices
should be avoided.

* Perl beutifiers can help in presenting the code well, but they still
don't usually re-write badly-written code for you.

* Some of those techniques can be applied after an initial version of the
code has been written. Others should better be thought about from the start.

Making your code look understandable:
---------------------------

1. Indent - even within the expressions.

Splitting statements is your friend:
------------------------------------

* Try to split complex statements (especially perl pipeline ones) into
several statements if possible.

If not possible - encapsulate inside inner closures and/or indent to show
the structure of the statement.

* Pass a s///e expression that becomes to complex into a function or a
closure.

Good (IMHO) Perl Style:
-----------------------

* Avoid using "$cond && print hello;" or "$cond and print hello" forms. It's
confusing for people who are used to other languages. Use if or unless
instead.

* The $_ variable - do not use it unless you have to - like in map or grep.
In the latter it is sometimes advisable to assign its value to a "my"
variable with a more meaningful name.

* use English;

9. Avoid using $var = eval { }, $var = do { }. Prefer the following form
my ($var);
{
    my $local_var1;
    my @local_array2;

    $var = [ expression or closure ]
}

Reason: people scan a code while having to remember that it is eventually
assigned to a variable.

* Always use return at the end of the function.

Writing Legibile Algorithms:
----------------------------

* splice - if can be replaced with a different functions (push, pop, a comma)
- should be. If not - better be put on its own statement.

* Put your ifs and whiles before the conditional block, not after the
statement.

* Emulating a do-while loop:
    a. with a closure.

        my $action = sub {
                [
                    Loop's body.
        	]
            };

        $action->();
        while($cond)
        {
            $action->();
        }

        Has the problem of an extra overhead.

    b. using a $perform_first_iter boolean.
        my $perform_first_iter = 1;
        while ($perform_first_iter || ( [ rest of condition ] ) )
        {
            $perform_first_iter = 0;
        }

    c. A goto-into the loop:
        goto after_condition;
        while ( [ condition expression ])
        {
        	after_condition:

        }
       Has the problem of a possible namespace collition if more than one
       such construct exists inside a function.

General Programming Methodologies (not specific to perl)
--------------------------------------------------------

* Comment your code with numerous and helpful comments.

* Use meaningful names for the variables.

* Write an architecture document if applicable.

----------------------------------------------------------------------
Shlomi Fish        [email-masked]
Home Page:         http://t2.technion.ac.il/~shlomif/
Home E-mail:       [email-masked]

A more experienced programmer does not make less bugs. He just realizes
what went wrong more quickly.

---

From: Omer Zak <[email-masked]>
Date: Wed, 8 Aug 2001 15:43:41 +0300 (EET DST)

Hello Shlomi,

My personal advice and preferences:
Don't bother with advice about understanding 50-line code blocks.
Advise how to make 10,000,000 line code base easier to understand.

This means:
1. Modularize.
2. Don't abuse object orientation.
3. Document arguments, results and side effects of functions.
4. Minimize obscure side effects of functions.
5. Describe in detail any non-trivial data structures (make liberal use of
   splice() but do explain the significance of the splices you are using).

etc. etc.

                                             --- Omer
There is no IGLU Cabal.  The former Cabal members argued for days where to
put the opening brace after if statements, and neglected the real
documentation needs of 10,000,000 lines long applications.
WARNING TO SPAMMERS:  at http://www.zak.co.il/spamwarning.html

---

From: Shlomi Fish <[email-masked]>
Date: Wed, 8 Aug 2001 15:58:37 +0300 (EEST)

> Advise how to make 10,000,000 line code base easier to understand.

Thanks for the advice, but I'm aiming at writing legible code at the code
block level. I don't expect most perl code to span 10,000,000 lines, and
moreover, most programmers will probably won't have to maintain such
large codebases.

My problem is that even small perl modules can become illigible and I want
to teach how to avoid it, if it's appropriate.

> 3. Document arguments, results and side effects of functions.

That's part of the commenting advice. However, I hope yoo agree that some
helper functions need not be documented.

Regards,

	Shlomi Fish

---

From: "Nadav Har'El" <[email-masked]>
Date: Wed, 8 Aug 2001 17:01:11 +0300

> Advise how to make 10,000,000 line code base easier to understand.

Your advice is similar to going to a guy explaining home-improvement on TV
and showing how to build a shelf (or whatever) well, and telling him: "don't
bother with advice about building a shelf - advise how to build a 150 story
sky-scraper!". True, if a someone is about to build a sky-scraper, they should
not bother with the details on how to make a shelf (they'll hire someone to
do that), but most people will never need to build a sky-scraper in their
lives, while building shelves is a useful skill.

Similarly, most hobyist (or even most professional) programmers will benefit
more from advice on writing 10,000 line programs than from advice on how to
write 10,000,000 lines.

-- 
Nadav Har'El                        |       Wednesday, Aug  8 2001, 19 Av 5761
[email-masked]             |-----------------------------------------
Phone: +972-53-245868, ICQ 13349191 |Tea or coffee? Coffee, without cream. It
http://nadav.harel.org.il           |will be without milk, we have no cream.

---

From: Omer Zak <[email-masked]>
Date: Wed, 8 Aug 2001 19:12:33 +0300 (EET DST)

> more from advice on writing 10,000 line programs than from advice on how to

OK, let's accumulate advice for documenting (not "writing") 10,000 line
programs.  It is much longer than 50-line code blocks, but within reach of
mortals, unlike 10,000,000 line programs.

                                             --- Omer
There is no IGLU Cabal.  Nadav said so 10,000 times.  And what Nadav says
10,000 times Is The Truth(TM).
WARNING TO SPAMMERS:  at http://www.zak.co.il/spamwarning.html

---

From: Shlomi Fish <[email-masked]>
Date: Wed, 8 Aug 2001 20:24:09 +0300 (EEST)

> mortals, unlike 10,000,000 line programs.

I don't care if you accomulate advice for writing 10,000 line programs,
but if you can please concentrate on 50-line blocks, too, because that's
what I'd like to write about.

Notice that I said "legible" code rather than "maintainable" code. If the
code is legible, but is a mess than the successor can easily re-write
parts of it. But if it is beutiful code that cannot be read and understood
properly, then the successor is down on his luck. He may be able to
decipher it eventually, but it will take some time.

So let's stay on topic shall we, even I don't mind this topic to go on.

Regards,

	Shlomi Fish

BTW, did you noticed that many Hackers-IL threads divert to something
else, after the second post? Oh well.

There is no IGLU Cabal!
The thread that was supposed to form it diverted to a related topic
before the Cabal could be formed.

---

From: "Nadav Har'El" <[email-masked]>
Date: Thu, 9 Aug 2001 00:08:10 +0300

> else, after the second post? Oh well.

Yes... Isn't the weather reallly annoying this time of year?

;)

-- 
Nadav Har'El                        |        Thursday, Aug  9 2001, 20 Av 5761
[email-masked]             |-----------------------------------------
Phone: +972-53-245868, ICQ 13349191 |We could wipe out world hunger if we knew
http://nadav.harel.org.il           |how to make AOL's Free CD's edible!