1. Do I need to put "use strict; use warnings;" at the top of my module?

Yes, Use strict and warnings applies to modules as well. If you see modules not doing that, then likey they are very old and/or not following best practices (or in some modern cases, they may be useing a module that enables them automatically - one example would be use Mojo::Base -strict;).

2. Should I start the perl module with #!/usr/bin/perl or is it okay to leave this off?

It's usually fine to leave it off. The shebang's primary use is when executing scripts from the shell on *NIX systems, or for CGI scripts, and since modules typically don't get executed directly, only used, the shebang isn't needed for that. (I did use to have a text editor that used the shebang to detect Perl scripts for its syntax highlighting, so a lot of my modules start with #!perl, but that's usually not needed otherwise.)

3. I think, I am going to write "use MyPackage;" in my perl program, and then myPackage.pm will be placed in my Perl's INC directory. Is this how it should be done?

Yes, that's the standard practice. require executes at runtime, while use executes at compile time, meaning that errors will be caught earlier, and also it calls the module's sub import if it has one, so it's the standard way of loading modules. You may also want to look into Exporter to provide the import functionality for you.

4. I've noticed that some modules have "our $VERSION = ..." but I start my module with "my $VERSION" Is that okay?
5. Btw what's the purpose of the $VERSION string? Is there a part of Perl that will try to access that value at some point during my program's execution?

our $VERSION is better, because some Perl utilities need access to the variable (like UNIVERSAL's ->VERSION), and some parse the $VERSION out of modules (like the CPAN indexer, IIRC).

6. What if my module's name conflicts with another module that exists out there?

The best thing would be to check the CPAN to avoid such conflicts entirely. But if it can't be avoided - one valid reason might be if you're monkey patching a module - and you don't plan on uploading your module to the CPAN, then the typical way to avoid conflicts on your local machine is to add a directory to @INC where you install the modules, making sure that directory appears first in @INC.

I notice you wrote "the INC directory" in several places; note there is more than one, and Perl searches them in order for modules, and you can add your own entries to the list in several different ways, e.g. use lib or the PERL5LIB environment variable. And typically, you wouldn't manually place your module into Perl's standard @INC directories, because that's the job of tools like cpanm, so instead you'd add your own directory to @INC so that you can manually modify the contents of that directory without messing up your Perl installation by accident.

7. What if my module tries to achieve the same result that another popular module does but mine goes about doing it very differently? How should I name my module?

That depends; if you plan to publish your code to the CPAN then I would recommend you ask for suggestions here by telling us what the modules are and how yours differs (both in functionality and in its API).

8. Is it important to upload a module to CPAN, or can I just put it on my website and host it there?

The advantage of the CPAN is that standard tools like cpanm can be used to install modules from there, and as you said, that it is likely to be around for longer. But putting modules on the CPAN does require a bit more work, since you have to put them in a distribution, providing proper documentation, a test suite, a Makefile.PL, and so on. You might want to look at module-starter for that.

9. When I open some pm files in the INC directory, I notice that a lot of them seem to have plain text mixed with program code. The text or documentation is preceded by something like "=head1 DESCRIPTION" and I am not sure what this is.
10. Is it's okay if I put my documentation on simple comment lines started with "#" instead of "=" ?

That's Plain Old Documentation (POD), and is described in perlpod (plus perlpodstyle, perlmodstyle, and perlpodspec). It's much better to use that instead of comments because the standard Perl tools like perldoc will automatically turn that into the nicely-formatted documentation you get when you run perldoc MyModule.pm and when you visit the CPAN website.

Here's all that applied to your example code:

package MyPackage;
use warnings;
use strict;
use Exporter 'import';

our @EXPORT_OK = qw/ myFunc /;

our $VERSION = "1.00";

=head1 myFunc()

This function is just a test.

=cut

my $PRIVATE = 444;

sub myFunc
{
  $PRIVATE++;
  print "\nPackage MyPackage::myFunc(@_)\nPRIVATE = $PRIVATE\n";
}

1;
[download]

And an example main code, where one quick way you can tell Perl how to find the module is perl -Ipath/to/package script.pl:

use warnings;
use strict;
use MyPackage qw/myFunc/;

myFunc();
[download]

Wow, thank you so much for answering all my questions so quickly and in such great detail!!!

I have one more question. I guess, I can look this up myself. My assumption is if the shebang is not mandatory for pm files in Linux (because pm files are not meant to be executed from command line), then I guess the file's permissions can be 644. They are not required to be 755. Correct?

My assumption is if the shebang is not mandatory for pm files in Linux (because pm files are not meant to be executed from command line), then I guess the file's permissions can be 644. They are not required to be 755. Correct?

Yes!

My assumption is if the shebang is not mandatory for pm files in Linux (because pm files are not meant to be executed from command line), then I guess the file's permissions can be 644. They are not required to be 755.

Yes. For cheap thrills, I ran these commands on my recently installed perl 5.38 on Ubuntu:

~/localperl$ find . -name '*.pm' -ls >pm.tmp
~/localperl$ find . -name '*.pl' -ls >pl.tmp
[download]

All the .pm files have permissions like this:

-r--r--r--   ... ./lib/5.38.0/Carp.pm
[download]

The perl commands in the bin directory designed to be run as commands have permissions like this example of the prove command:

-rwxr-xr-x  ... prove
[download]

These text files also tend to start with a shebang line like:

#!/home/youruser/localperl/bin/perl
[download]

There are also plenty of .pl files lying around with permissions like this:

-r--r--r-- ... somefile.pl
[download]

which is fine because you can still run them manually via:

perl /somepath/somefile.pl
[download]

I came back - my back is hurting and couldn't sleep....

There is one trick that I sometimes use....
It is possible for your module to know if it was "used" versus executed directly. This allows me to put a test driver in the module itself that I use during development that presents more info that just a "pass/fail". If you do this, you will want your .pm to be an executable file under Unix.

#Normal module preamble here...
sub test{
   print "this is a dev test...\n";
}

test() if not caller; ### Run test() if run directly

#Normal rest of module code here....
1;
[download]

Also for #1 where something else enables them, use can implicitly enable strict or warnings depending on the version.

See use VERSION

haukex has already provided mind-bogglingly excellent answers to each of your ten questions. As a starting point, I suggest you start with his sample MyPackage given at the end of his reply, and then gradually flesh it out, learning as you go. Feel free to post early versions here for feedback.

As time permits, you might also like to browse through my humungous Writing Solid CPAN Modules looking for any topics that you have a special interest in.

I still remember the steep learning curve when writing my first Perl module. Lots to learn, but very rewarding. Good luck with your first Perl module!

Lots of good info! Thank you very much!!

you alredy had very good replies so I can just add few cents.. for example you might like to browse some link in my bibliotheca

No one mentioned something very important: tests! In my opinion good software consists of 3 ingredients: code, tests and documentation. No one of these 3 can be poor to have a nice resulting recipit.

You can also take a look to my step-by-step-tutorial-on-perl-module-creation-with-tests-and-git.

Share the code soon and consider also a visit to prepan.org. (see below)

Have fun!

L*

Thank you for the resources! Now I have plenty to read.

Btw prepan.org seems to be about computer programming, but it's all written in Chinese. Is that the correct link?

PrePAN is no more. It used to be a place where module authors could ask about module issues (like naming) before releasing the modules to CPAN.

Edit: Oops, I missed that Discipulus already replied.

..oops sorry if I didnt checked :( goodbye-prepan

L*

There are no rules, there are no thumbs..
Reinvent the wheel, then learn The Wheel; may be one day you reinvent one of THE WHEELS.

Are you writing a module for your own use or are you planning on releasing a module on CPAN for use by others? Doing the former is easier and I would recommend doing that before trying to make a module release.

Yes, I am planning to write the module for personal use first. And if it seems to be useful and work without any glitches and I can write the documentation for it, I may release it on my website... and maybe CPAN as well. The latter one seems to be a lot of extra work, but I will study the link you posted. Thank you!

Addenda:

• perlstyle
• perltidy
• Naming convention
• Intention Style
• Self testing Perl modules using the Modulino concept

Just a nitpick: the case is important. On some systems (e.g. linux), MyPackage.pm and myPackage.pm can be two files coexisting in the same directory.