Looks like if you just swap the two variables names (just in the declaration lines), then it makes sense.

Firing up Acme::ESP, I suspect the author was thinking of the IV as an opaque thing that refers to the real object ("Soldier") and the RV was the Perl (proxy) object. So he called the IV "obj_ref" and the Perl object "obj" but then, when writing the rest of the code, he naturally used "obj_ref" to get the Perl reference and "obj" to get what would result from de-ref-ing "obj_ref".

So, if you have two different things that are "objects" and one refers to the other and one is also a Perl reference, then "obj" and "ref" are way too ambiguous to be enough to get good variable names.

SV* new( char* class, char* name, char* rank, long serial )
{
    Soldier* soldier;
    SV*      addr;
    SV*      perlObj;
    
    New( 42, soldier, 1, Soldier );
    soldier->name = savepv(name);
    soldier->rank = savepv(rank);
    soldier->serial = serial;

    addr = newSViv( (IV)soldier );
    SvREADONLY_on( addr );
    perlObj = newSVrv( addr, class );

    return perlObj;
}
[download]

But I'd avoid most of the "writing Perl code in C" of such an XS example and instead have the XS functions provide a C-like interface and use Perl wrappers to do the Perl stuff. You'll end up with more flexible code with fewer bugs that way, IME.

IV new( char* class, char* name, char* rank, long serial )
{
    Soldier* soldier;

    New( 42, soldier, 1, Soldier );
    soldier->name = savepv(name);
    soldier->rank = savepv(rank);
    soldier->serial = serial;

    return (IV)soldier;
}
[download]