Re: guidance on naming my first module for CPAN
by eyepopslikeamosquito (Archbishop) 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
| [reply] [d/l] [select] |
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
| [reply] |
|
| [reply] |
Re: guidance on naming my first module for CPAN
by 1nickt (Canon) 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.
| [reply] [d/l] [select] |
|
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.
| [reply] [d/l] |
|
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.
| [reply] [d/l] [select] |
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.
| [reply] |
Re: guidance on naming my first module for CPAN
by ikegami (Patriarch) on Jan 23, 2021 at 22:43 UTC
|
| [reply] [d/l] [select] |
Re: guidance on naming my first module for CPAN
by salva (Canon) on Jan 24, 2021 at 07:31 UTC
|
Data::QuickMemoPlus::Reader | [reply] [d/l] |