You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: source/tutorial-english.html
+31-31Lines changed: 31 additions & 31 deletions
Original file line number
Diff line number
Diff line change
@@ -44,7 +44,7 @@ <h1>Discipulus's step by step tutorial on module creation with tests and git</h1
44
44
45
45
46
46
47
-
<ahref="#daytwo"><h4>day two: some change and tests</h4></a>
47
+
<ahref="#daytwo"><h4>day two: some changes and tests</h4></a>
48
48
<ul>
49
49
<li>
50
50
<ahref="#daytwostep1">step 1) POD documentation</a>
@@ -493,23 +493,23 @@ <h4>step 3) a local repository with git</h4>
493
493
494
494
495
495
<aid="daytwo"></a>
496
-
<h2>day two: some change and tests</h2>
496
+
<h2>day two: some changes and tests</h2>
497
497
498
498
499
499
<aid="daytwostep1"></a>
500
500
<h4>step 1) POD documentation</h4>
501
501
502
-
Well first of all some cleaning: open you local copy of the module <code>/path/to/Range-Validator/lib/Range/Validator.pm</code> in your text editor or IDE. Personally I like the POD documentation to be all together after the <code>__DATA__</code> token rather interleaved with the code. Inside the code I only like to have comments. POD documentation is for the user, comments are for you! After a week or month you'll never remember what your code is doing: comment it explaining what is passing.
502
+
Well first of all some cleaning: open you local copy of the module <code>/path/to/Range-Validator/lib/Range/Validator.pm</code> in your text editor or IDE. Personally I like the POD documentation to be all together after the <code>__DATA__</code> token rather than interleaved with the code. Inside the code I only like to have comments. POD documentation is for the user, comments are for you! After a week or month you'll never remember what your code is doing: comment it explaining what is happening.
503
503
504
-
So go to the end of the module where the line is the final <code>1;</code> ( remember all modules must have a true return value as last statement) and place, in a new line the <code>__DATA__</code> token. Move all POD after the token. Also cancel the POD and the code relative to<code>function2</code>
504
+
So go to the end of the module where the line is the final <code>1;</code> ( remember all modules must return a true value in their last statement) and add in a new line the <code>__DATA__</code> token. Move all POD after this token. Also remove the POD and the code of<code>function2</code>
505
505
506
-
Then rename <code>function1</code>into<code>validate</code> and change accordingly the name of the POD section too.
506
+
Then rename <code>function1</code>to<code>validate</code> and change the name of the POD section accordingly.
507
507
508
-
Modify the POD part <code>=head1 NAME</code> with a more humble and meaning description: <code>Range::Validator - a simple module to verify array and list ranges</code>
508
+
Modify the POD part <code>=head1 NAME</code> with a more humble and meaningful description: <code>Range::Validator - a simple module to verify array and list ranges</code>
509
509
510
-
Change the <code>=head1 SYNOPSIS</code> part too, removing unneeded text and changing code lines ( see below ): we do not do an object oriented module, so no <code>new</code> method for us. You plan to accept both real ranges and strings representing ranges.
510
+
Change the <code>=head1 SYNOPSIS</code> part too, removing unneeded text and changing code lines ( see below ): we're not doing an object oriented module, so no <code>new</code> method for us. The plan is to accept both real ranges and strings representing ranges.
511
511
512
-
So, if you followed me, the module must look like:
512
+
So, if you followed along, the module will look like:
513
513
<pre>
514
514
package Range::Validator;
515
515
@@ -551,9 +551,9 @@ <h4>step 1) POD documentation</h4>
551
551
# more POD ...
552
552
553
553
</pre>
554
-
Ok? Let's check our new POD is correct: open the shell in the directory created yesterday <code>/path/to/Range-Validator</code> and run the following command: <code> perldoc ./lib/Range/Validator.pm </code>
554
+
Ok? Let's check if our new POD is correct. Open the shell in the directory created yesterday <code>/path/to/Range-Validator</code> and run the following command: <code> perldoc ./lib/Range/Validator.pm </code>
555
555
556
-
Review the POD. It must be ok.
556
+
Review the POD and make sure it is ok.
557
557
558
558
559
559
<aid="daytwostep2"></a>
@@ -568,13 +568,13 @@ <h4>step 2) first test</h4>
568
568
569
569
shell>
570
570
</pre>
571
-
No errors: good! the module can be used and has no syntax errors. But.. one moment: we want to try out all our features, and we plan to add many, using one liners? Are we mad?! No; we will use tests.
571
+
No errors. Good! The module can be used and has no syntax errors. But.. one moment: we want to try out all our features, and we plan to add many, using one liners? Are we mad?! No; we will use tests.
572
572
573
-
Tests are wonderful in perl and planning good tests (a test suite) will save a lot of time in the future and makes your code maintainable. The time you invest writing tests <b>while coding</b> will save a lot of time in the future when you modify the code base. I'm not a theoric of software writing nor an orthodox of test driven development, but to write tests while you code is a very good practice. You can even write tests <b>before coding</b>ie: you write something that test a wanted behaviour, you run it expecting a failure, then you write the code that make the test happy. This is up to you.
573
+
Tests are wonderful in perl and planning good tests (a test suite) will save you a lot of time in the future and makes your code maintainable. The time you invest in writing tests <b>while coding</b> will save you a lot of time when you modify the code base. I'm not an authority on software writing, nor do I strictly adhere to test driven development, but to write tests while you code is a very good practice. You can even write tests <b>before coding</b>i.e. you write something that tests a wanted behaviour, you run it expecting a failure, then you write the code that makes the test happy. This is up to you.
574
574
575
575
What is not a choice is having no test suite or writing all tests at the end of code development. No.
576
576
577
-
In the day one we used <code>module-starter</code> to produce a skeleton of our module. <code>module-starter</code> was so kind to write a bounch of tests for us in the standard directory <code>/t</code> (ie tests). Tests are run normally during the installation (sorted by their names) of the module but, as we already said, they are the main source of serenity for us as developers. So let's see what <code>module-starter</code> wrote inside <code>/t/00-load.t</code>
577
+
In day one we used <code>module-starter</code> to produce a skeleton of our module. <code>module-starter</code> was so kind to write a bunch of tests for us in the standard directory <code>/t</code> (i.e. tests). Tests are run normally during installation (sorted by their names) of the module but, as we already said, they are the main source of serenity for us as developers. So let's see what <code>module-starter</code> wrote inside <code>/t/00-load.t</code>
This perl program use strict and wanrings (you already know they are friends, do you?) then load the core module <ahref="https://perldoc.perl.org/Test/More.html">Test::More</a> which generally
596
-
requires that you declare how many tests you intend to run ( <code>plan tests => 1</code> ) then inside the <code>BEGIN</code> block use its method <code>use_ok</code> that loads our own module and in case of failure print "Bail out!\n" aka "everything went wrong, leave the boat".
595
+
This perl program uses strict and warnings (you already know they are your friends, don't you?) then loads the core module <ahref="https://perldoc.perl.org/Test/More.html">Test::More</a> ( which generally
596
+
requires that you declare how many tests you intend to run ( <code>plan tests => 1</code> )), then inside the <code>BEGIN</code> block uses its method <code>use_ok</code> that loads our own module and in case of a failure prints "Bail out!\n" aka "everything went wrong, leave the boat".
597
597
598
-
If the above succeeded <ahref="https://perldoc.perl.org/Test/More.html">Test::More</a> calls <code>diag</code> that emits a note with the text specified, useful to have while reviewing test output. The module also has the <code>note</code> method that I prefer. Go to the module documentation to have an idea of <ahref="https://perldoc.perl.org/Test/More.html">Test::More</a>
598
+
If the above succeeded <ahref="https://perldoc.perl.org/Test/More.html">Test::More</a> calls <code>diag</code> that emits a note with the specified text, useful to have while reviewing test output. The module also has the <code>note</code> method, which I prefer. Go to the module documentation to learn more of <ahref="https://perldoc.perl.org/Test/More.html">Test::More</a>
599
599
600
600
So, instead of the one liner we can safely call this test:
601
601
@@ -605,9 +605,9 @@ <h4>step 2) first test</h4>
605
605
"-T" is on the #! line, it must also be used on the command line at ./t/00-load.t line 1.
606
606
607
607
</pre>
608
-
The test crash because of the <code>-T</code> that turns taint mode on. Taint mode is base of the security in perl, but for the moment we do not need it enabled, so we remove from the shebang line which will result in <code>#!perl</code> (read about taint mode in the official perl documentation: <ahref="https://perldoc.perl.org/perlsec.html#Taint-mode">perlsec</a>).
608
+
The test crashes because of the <code>-T</code> that turns taint mode on. Taint mode is a basic security protection in perl, but for the moment we do not need it enabled, so we remove <code>-T</code>from the shebang line which will result in <code>#!perl</code> (read about taint mode in the official perl documentation: <ahref="https://perldoc.perl.org/perlsec.html#Taint-mode">perlsec</a>).
609
609
610
-
(Note that removing <code>-T</code> switch is not the best thing to do: <code>perl -T -I ./lib ./t/00-load.t</code> is by far a better solution).
610
+
(Note that removing the <code>-T</code> switch is not the best thing to do: <code>perl -T -I ./lib ./t/00-load.t</code> is a far better solution).
Wow! we run our first test! ..yes, but in the wrong way. Well not exactly the wrong way but not the way tests are run during installation.
623
-
Test are run through a TAP harness (TAP stands for Test Anything Protocol and is present in perl since ever: perl born the right way ;).
622
+
Wow! We ran our first test! ..Yes, but in the wrong way. Well not exactly the wrong way but not the way tests are run during installation.
623
+
Test are run through a TAP harness (TAP stands for Test Anything Protocol and is present in perl since forever: perl was born the right way ;).
624
624
625
-
With your perl distribution you have the <ahref="https://perldoc.perl.org/prove.html">prove</a> command (see its documentation) that run tests through a TAP harness. So we can use it.
625
+
With your perl distribution you have the <ahref="https://perldoc.perl.org/prove.html">prove</a> command (see its documentation) that runs tests through a TAP harness. So we can use it.
626
626
627
-
We can call <ahref="https://perldoc.perl.org/prove.html">prove</a> the very same way we called perl: <code>prove -I ./lib ./t/00-load.t</code> but we are lazy and we spot <code>prove -l</code> which has the same effect of<code>prove -I ./lib</code>ie include <code>./lib</code> in <code>@INC</code>
627
+
We can call <ahref="https://perldoc.perl.org/prove.html">prove</a> the very same way we called perl: <code>prove -I ./lib ./t/00-load.t</code> but we are lazy and we spot <code>prove -l</code> which has the same effect as<code>prove -I ./lib</code>i.e. include <code>./lib</code> in <code>@INC</code>
628
628
629
-
Run the very same test through <ahref="https://perldoc.perl.org/prove.html">prove</a> instead that perl and you will see a slightly different output:
629
+
Run the very same test through <ahref="https://perldoc.perl.org/prove.html">prove</a> instead of perl and you will see slightly different output:
630
630
631
631
<pre>
632
632
shell> prove -l ./t/00-load.t
@@ -638,11 +638,11 @@ <h4>step 2) first test</h4>
638
638
Result: PASS
639
639
640
640
</pre>
641
-
Basically the output includes some statistics and the count of test files processed and the overall number of tests. Also note that the message emitted by <code>diag</code> is in another place: diagnostics by<ahref="https://perldoc.perl.org/Test/More.html">Test::More</a> goes to <code>STDERR</code> (which is buffered differently in respect of <code>STDOUT</code> but this is another story..) and TAP aggregates tests results and prints them to <code>STDOUT</code>
641
+
Basically the output includes some statistics and the number of test files processed and the overall number of tests. Also note that the message emitted by <code>diag</code> is in a different place: diagnostics from<ahref="https://perldoc.perl.org/Test/More.html">Test::More</a> goes to <code>STDERR</code> (which is buffered differently from <code>STDOUT</code> but this is a different story..) and TAP aggregates test results and prints them to <code>STDOUT</code>
642
642
643
-
Finally we have the developer gratification: <code>Result: PASS</code> indicating all went well.
643
+
Finally we have the gratifying: <code>Result: PASS</code> indicating all went well.
644
644
645
-
The <code>prove</code> program promotes laziness and without argument (as a test file in the previous example) runs automatically every test file found under <code>/t</code> folder: this is the same behaviour you will have during an effective module installation:
645
+
The <code>prove</code> program promotes laziness and without arguments (such as the test file in the previous example) automatically runs every test file found under the <code>/t</code> folder: this is the same behaviour you will have during module installation:
646
646
647
647
<pre>
648
648
shell> prove -l
@@ -663,7 +663,7 @@ <h4>step 2) first test</h4>
663
663
<aid="daytwostep3"></a>
664
664
<h4>step 3) commit changes with git</h4>
665
665
666
-
Ok we have done some change to the code base, small ones but changes. Wich changes? I'm lazy and I do not remember all files we modified. No problem <code>git</code> will tell us. At least I remember which command I need to review the code base status: <code>git status</code>
666
+
Ok we have done some changes to the code base, small changes but still changes. Which changes? I'm lazy and I do not remember all files we modified. No problem <code>git</code> will tell us. At least I remember which command I need to review the code base status: <code>git status</code>
667
667
668
668
Go to the git shell and run it:
669
669
@@ -681,9 +681,9 @@ <h4>step 3) commit changes with git</h4>
681
681
no changes added to commit (use "git add" and/or "git commit -a")
682
682
683
683
</pre>
684
-
Ah yes, we modified two files: not only the modulealso the <code>t/00-load.t</code> removing the <code>-T</code> from shebang line, thanks <code>git</code> and you are also so kind to give me two hints about what to do next: <code>use "git add" and/or "git commit -a"</code>
684
+
Ah yes, we modified two files: not only the module, but also the <code>t/00-load.t</code> removing the <code>-T</code> from the shebang line, thanks <code>git</code> and you are also so kind to give me two hints about what to do next: <code>use "git add" and/or "git commit -a"</code>
685
685
686
-
Go for the shorter path: we commit adding all files with <code>git commit -a</code>ie: we commit all files <b>that are already tracked</b> and eventually we remove from tracked list all files deleted in the code base. But we remember that committing needs to include a message as label of the commit: <code>git commit -m "message"</code> so putting all together and checking the status:
686
+
Go for the shorter path: we commit adding all files with <code>git commit -a</code>i.e. we commit all files <b>that are already tracked</b>(and eventually we'll remove from the tracked list all files deleted in the code base). But we remember that committing needs to include a message as label of the commit: <code>git commit -m "message"</code> so putting it all together and checking the status we do:
687
687
688
688
<pre>
689
689
git-client> git commit -a -m "moved POD, removed -T"
@@ -730,9 +730,9 @@ <h4>step 4) pushing to github repository</h4>
730
730
1788c12..49a0690 master -> master
731
731
732
732
</pre>
733
-
Go to the browser and open the online repository to see what happened after the <code>git push</code>: in the main page, where files are listed we spot our two modified files with a new timestamp and with the message we used when committing. Under the Insight tab and then under Network in the right menu, we can see two points connected by a line segment: this is the visual history of our repository and each commit we have done: here you will find also eventual branches, but this is another story.
733
+
Go to the browser and open the online repository to see what happened after the <code>git push</code>: in the main page, where files are listed we spot our two modified files with a new timestamp and with the message we used when committing. Under the Insight tab and then under Network in the right menu, we can see two points connected by a line segment: this is the visual history of our repository and each commit we have done: here you will find also eventual branches, but this is a different story.
734
734
735
-
Well, another day is passed without writing a single line of perl code! At least for the moment our code is 100% bug free ;)
735
+
Well, another day has passed without writing a single line of perl code! At least for the moment our code is 100% bug free ;)
736
736
I vaguely recall a chinese motto: "when you start something, start from the opposite" or something like that. To write a robust perl module start writing no perl code, for two days!
0 commit comments