Thread: [sendpage-devel] SoC Status Report for Week 1+

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Status Report for Week 1
========================

Hi all,

This is my first status report for the week (actually more than a
week, counting from May 25.)  I have been unavoidably delayed in
writing this report due to some other concerns (closing of summer,
etc.) but nonetheless I have not faltered in devoting a couple of
hours or more every day in these past few days for this project.

So as to prove that I have not been `slacking around' and just
waiting for Godot, here's my `bits from the Sendpage SoC-er' (as
inspired from similar mailings to debian-devel, et al. by project
participants):

Phase 1: Planning and Research
==============================

Following the original project schedule[0] as included in my
proposal, I have been reading the code for the Sendpage system (the
main driver and library modules) and the accompanying documentation
to further my understanding of the entire system.  I even went so
far as to actually print down the CVS source code in paper and do my
annotations by pen since the existing code was quite small.  This
`grokking' of the code has led me to relearn certain Perl
constructs, including the different ways of describing classes, as
well as utility constructs such as file locking.

[0]  http://zakame.spunge.org/pub/soc2006/OSDL_sendpage-enhancements.txt

To aid my browsing of the CVS code tree (and my modifications to it)
I have elected to set up a local RCS repository which I can
interface with my text editor.[1] (I suppose many veteran FOSS
developers are already aware of this setup, but I feel I'm not too
old to learn new things. ;)

[1]  http://www.gnu.org/software/emacs/manual/html_node/Local-Version-Control.html

Queries and Observations regarding Sendpage::Device
---------------------------------------------------

Among the first things Kees hinted at me for my attention was
looking into Sendpage::Device and Sendpage::Db and look for places
to improve.  Indeed, I have noted several places in Sendpage::Device
that seems to stick out of the woodwork.  Here are some of the
things I have noticed:

  - Device.pm describes itself as `a wrapper for either Modem.pm or
    TCPModem.pm'; however, looking at Modem.pm's code (there is no
    TCPModem.pm, btw) it seems that Device.pm duplicates much of
    Modem.pm's code, with only little additions in the latter
    module.  Perhaps Device.pm is intended to replace Modem.pm at
    some point in the future, or that Sendpage::Modem be a derived
    class from Sendpage::Device(?)

  - The Perl `metagoofs' of _not_ using the `warnings' and `strict'
    pragmas as appropriate are evident in all modules of the code.
    Being pretty much green (but not too much) to Perl, I have been
    led to believe that good Perl code ought to avoid these
    metagoofs, especially for publicly-available programs and
    modules.  I suppose by turning these strictures on, I and other
    will be able to catch the many `gotchas' in Sendpage's
    programming, and may ultimately lead to better, more
    maintainable code.

  - Sendpage::Device's new() method seems to do some file locking
    using sysopen() without flock().  While I do suppose that this
    works nicely, I feel that the code for this can be improved by
    making use of constructs made convenient in Perl, such as
    Highlander-style locking.[2] I am still looking for a better way
    to do this, since other programs such as minicom enforce a
    particular style of locking modems...

    [2]  http://perlmonks.org/?node_id=14260

  - There's a lot of duplicated code within Sendpage::Device's
    methods.  The new() and init() methods, for example, seem to be
    very long, since much of the initialization code (in if() tests)
    make calls to the log object for the device before proceeding.
    Perhaps wrapping this around an anoymous subroutine to be called
    later would be more efficient for both machine and programmer :/
    ...

  - Last (but not the least) is perhaps the main object of the
    enhancements project: making the object configuration code
    simpler and easier to understand.  From my reading, it seems
    that Sendpage::Device (and probably the other class modules too)
    do their attribute initialization and configuration in methods
    other than their constructors; while this is not bad in general,
    this style of object initialization, in my experience, has led
    to confusing code, since it will be less obvious for a user to
    manipulate an object and its attributes in the long term.
    Anyhow, this also defeats the encapsulation provided by the
    imposed object system.

Preliminary Coding Work
-----------------------

To help myself in understanding the above observations better, I have
started diving into the actual code and putting down my modifications to
it.  While I do not have CVS commit access at the moment, I am making
that up by keeping my modifications inside RCS, where I can easily
switch to and from CVS/RCS using the facilities provided by Emacs'
VC-mode.  Much of my modifications have been in putting down my
hand-written annotations to the code for documentation, as well as
reindenting; I noticed that there doesn't seem to be a unifying coding
style to follow (some of the other modules have different indent levels,
others have trailing and leading whitespace, etc.) so I settled in
enforcing one.

In the long run, I suppose I can classify my changes to Sendpage in two
kinds, the first being (a) documentation fixes, and (b) code
restructuring.  With that classification, I think it would be best to
put doc fixes in a the current mainline, while having the major code
changes in a separate branch.

Next Steps
==========

With what I have learned this past week, I feel confident that I can
now work on proceeding with formulating a coherent design
specification for improving Sendpage and its associated modules (I
personally feel that the sendpage program itself it quite big, and
that seems to be an indication for further redesign.)  Also, since I
have been focusing on the program almost entirely for its Perl
nature from the start, I can now move on to understand the
underlying protocols that Sendpage implements, namely TAP and SNPP,
in the hopes of working on features outlined in the TODO and
enriching the existing documentation.

__END__

Erm, I feel that this email has gotten long enough.  I thank you in
advance for getting to this part. :D If you have some comments, pointers
for further improvement, and (constructive) criticism, they're very
welcome; just drop a line to this post.

I suppose this document itself can be improved; I've been pretty too
formal in writing this, IMO.  Well, I'll get some more practice in
the weeks to follow ;P

Cheers,

Zakame

-- 
Zak B. Elep  ||  http://zakame.spunge.org
za...@ub...  ||  za...@sp...
1486 7957 454D E529 E4F1  F75E 5787 B1FD FA53 851D