Beefy Boxes and Bandwidth Generously Provided by pair Networks
P is for Practical
 
PerlMonks  

Re: How to document complex data structures?

by wazzuteke (Hermit)
on Oct 21, 2007 at 15:31 UTC ( #646273=note: print w/ replies, xml ) Need Help??


in reply to How to document complex data structures?

That's always an interesting question when it comes to non-typed languages. There are a couple things I try to keep in mind when commenting on the method signature of most things I'm working on:

1.) Return more than one value
In my opinion, data structures are like objects in that they need to have a generic, singular purpose. I try to avoid having to explain why a hash-ref or an AoH has data on three different and otherwise exclusive things just to maintain a single reference in code. That's just as confusing as anything. In your example, you have an array returning hash-refs that are completely different from one another. I can't, for example, take the list and iterate over it expecting a single DDL. I would either have to test for a key, or shift off the stack and hope things are in the right order. There is no real good way to document something like this.

A recommendation on this would be to simply break up the AoH into singular hashes. For each, either return a defined structure from a sinle method (ie return $href_original, $href_changes ... . Or, have many methods that return the respective piece of data. This way, you can not only comment on what is happening, but the code is a bit more self-documenting as well.
Such as:

# # Intended to be the caller # my $originals = $self->get_originals(); my $changes = $self->get_changes(); # # Intended to be the 'offending' package # ... sub get_originals { return $_[0]->{'original'}; } sub get_changes { return $_[0]->{'changes'} }

2.) Don't be afraid to comment with structures and text
The point being, really, that commenting with a pseudo-structure is sometimes the best way to describe what something should look at. Furthermore, comments aren't ususally pointed at yourself (at least I tend to remember code I've written, for the most part). That said, if a cohort doesn't understand the look of a complex data structure either a) They shouldn't be programming Perl b) They will ask someone anyways (me or otherwise). Furthermore, adding text around the structure to explain what they keys *are*, not just their data-type is always useful.

This could really go on and on, and I'm sure by the time I've posted this there is already three other good examples. The point I am really trying to make is: make sure your structures make sense in the first place *then* don't be afraid to use pseudo-code as a descriptive characteristic in the comments of a method signature.

---------
perl -le '$.=[qw(104 97 124 124 116 97)];*p=sub{[@{$_[0]},(45)x 2]};*d=sub{[(45)x 2,@{$_[0]}]};print map{chr}@{p(d($.))}'


Comment on Re: How to document complex data structures?
Select or Download Code

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://646273]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others making s'mores by the fire in the courtyard of the Monastery: (12)
As of 2015-07-06 10:28 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    The top three priorities of my open tasks are (in descending order of likelihood to be worked on) ...









    Results (71 votes), past polls