Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl: the Markov chain saw
 
PerlMonks  

guidance on naming my first module for CPAN

by Lotus1 (Vicar)
on Jan 23, 2021 at 22:05 UTC ( #11127342=perlquestion: print w/replies, xml ) Need Help??

Lotus1 has asked for the wisdom of the Perl Monks concerning the following question:

I'm looking for guidance on naming my first module for CPAN. So far I've been calling it

LG::QuickMemo_Plus::Extract::Memo

The purpose of the module is to help me extract the large number of memos I have written on my LG smartphone in QuickMemo+. The module extracts the memo text from the lqm files that QuickMemo+ exports. I couldn't find any software that could open those files other than 7zip. The lqm file is actually a zip file that contains a JSON file that contains the memo text so it was an easy module to write. Each memo is in a separate archive so it is very tedious to extract each memo by hand.

My questions are:

  • Is this name acceptable for CPAN? Some other options I considered are:
    • LG::QuickMemo_Plus::Memo::Extract
    • LG::QuickMemo+::Memo::Extract
    • QuickMemo_Plus::Memo::Extract
    • QuickMemo_Plus::Extract::Memo
    • QuickMemo_Plus::Extract
  • Is a module like this needed on CPAN?
    • I'm thinking it might be better to just make a small GUI and release the binary on Github. My plan is to do both. But I wonder how many Perl programmers would be interested in this module.

Replies are listed 'Best First'.
Re: guidance on naming my first module for CPAN
by eyepopslikeamosquito (Bishop) on Jan 24, 2021 at 00:27 UTC

    Though I quite like davido's later suggestion of Data::QuickMemoPlus::Extract, I bring your attention to a general piece of naming advice from Writing Solid CPAN Modules, namely that Perl Best Practices, in the item "Use grammatical templates when forming identifiers", recommends a module naming template of:

    Abstract_noun Abstract_noun::Adjective Abstract_noun::Adjective1::Adjective2
    For example:
    package Disk; package Disk::Audio; package Disk::DVD; package Disk::DVD::Rewritable

    Based on that advice -- since "extract" is a verb (not an adjective) -- perhaps extract should be a method name in module Data::QuickMemoPlus.

    Update: Given that Extract is a verb (or could be a noun depending on context), Extractor a noun, and Extractable an adjective, you could play around with names like:

    Data::Extractor::QuickMemoPlus Data::Extractable::QuickMemoPlus Data::QuickMemoPlus::Extractor
    Further update: ... I now prefer salva's suggestion: Data::QuickMemoPlus::Reader

Re: guidance on naming my first module for CPAN
by GrandFather (Saint) on Jan 23, 2021 at 23:11 UTC

    I'd look to see where it might fit into CPAN's current hierarchy. A MetaCPAN search on Extract may help. As a general thing you should avoid generating top level nodes on CPAN and neither LG nor QuickMemo\w* are current top level nodes.

    Optimising for fewest key strokes only makes sense transmitting to Pluto or beyond

      This "top level" discussion is a good call. Perhaps something in the Data:: namespace. Data::QuickMemoPlus::Extract, for example.


      Dave

Re: guidance on naming my first module for CPAN
by 1nickt (Abbot) on Jan 23, 2021 at 23:44 UTC

    Hi, thank you for doing the right thing and asking first!

    You have three excellent answers, but I'd side with the learned Grandfather over the learned davido on whether or not to create a new top-level namespace. In this case it's certainly not needed as you have the Device:: top-level space, where there are already sub-names representing commercial brands, eg Nest ...

    So my humble recommendation, since the software is exclusive to LG, would be that you create a top level package at Device::LG::QuickMemoPlus and put your functions in a subclass Device::LG::QuickMemoPlus::Extract. I find this straightforward and descriptive and that it leaves room for you or other authors to add other packages under the namespace in future.

    Hope this helps!


    The way forward always starts with a minimal test.

      This is a big help, thank you!

      Your answer brings up a question however. Do I need to do anything special in my package to specify the package name without the name of the pm file? In other words when I submit Device::LG::QuickMemoPlus::Extract.pm the folder structure in lib/ stops at QuickMemoPlus. Does that tell CPAN what the top level package is?

      I'm planning to use Minilla to help me make the build file so I was hoping it would handle these things. Maybe this would be a good place to start a new thread for help with Minilla when I get stuck.

      Update:

      After looking through the modules in the Device namespace I noticed that they are modules used for interfacing to devices. I'm starting to think the Data namespace as others have suggested might be better. It would be nice to have the option of using the module to find the device and get the extract files directly instead of requiring the user to move them somewhere first. I'm going to wait for a few days to let it percolate before I try to upload anything.

        Hi again,

        You'd have in your distribution:

        lib/ lib/Device/ lib/Device/LG/ lib/Device/LG/QuickMemoPlus.pm lib/Device/LG/QuickMemoPlus/ lib/Device/LG/QuickMemoPlus/Extract.pm
        ... and your package names would start at Device:
        lib/Device/LG/QuickMemoPlus.pm -> package Device::LG::QuickMemo lib/Device/LG/QuickMemoPlus/Extract.pm -> package Device::LG::QuickMem +o::Extract

        Hope this helps!


        The way forward always starts with a minimal test.
Re: guidance on naming my first module for CPAN
by davido (Cardinal) on Jan 23, 2021 at 23:00 UTC

    I would probably favor QuickMemoPlus::MemoExtract because I don't like mixing snake case and camel case if I can help it. (Doing so comes in handy sometimes, but this doesn't seem like that time.) I don't think that the name LG adds anything. QuickMemo+ is the software you're targeting, and Extracting a Memo is what you're doing.

    We will never know if it's needed on CPAN, but its existence on CPAN wouldn't be wrong. Try to make it a model citizen, though; a good test suite, good documentation, etc. That way even if it doesn't get used heavily, or at all, it can stand as an example of a well crafted distribution.


    Dave

Re: guidance on naming my first module for CPAN
by ikegami (Pope) on Jan 23, 2021 at 22:43 UTC

    Just two quick tips: + is not an acceptable character. And _ is avoided in module names.

Re: guidance on naming my first module for CPAN
by salva (Canon) on Jan 24, 2021 at 07:31 UTC
    Data::QuickMemoPlus::Reader

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://11127342]
Approved by choroba
Front-paged by ikegami
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others browsing the Monastery: (6)
As of 2021-04-16 11:40 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found

    Notices?