POPP Diary #5 - The Grind of Chapter 4
Did I promise a Monday diary? Yes I did. Am I delivering? Apparently not. Well, the book must come first, so I’m not entirely repentant. The reality is that this diary will likely get thinner as the demands of the book increase and, while revisiting many hundreds of code examples to for checks and upgrades is essential work it does not necessarily make for good copy.
All this work has given me an idea for a new book – Writing for Geeks. I’ll mull that one over. It’s definitely a niche market so perhaps not worth the investment. If you’d be interested in a book like that, ping me on Twitter.
Anyway, as I say, week five began with no diary blog – though, luckily, I am keeping a rough log as I go so I don’t have to dredge it all up from memory.
The entire week was taken up with the monster Chapter 4 which weighed in at a whopping 120 code examples. That’s a lot given that each individual example is invoked by a runner, a test, often both and often talks to a bunch of other classes that aren’t included in the copy.
Because I reorganised some code examples and wrote a few more, I had to do a certain amount of renumbering and reflowing. I’m now very glad I took time out to write tools for this. I can’t imagine having to hand edit forty code entries just to readjust numbering. The trick is commit everything to git, run the code generator and then check git diff. If the only thing that has changed in the file is the code example numbering, then I know it hasn’t all gone wrong.
A lot of the tests in Chapter 4 really only ran the example code without checking it, so much of the week was taken up with finishing the tests properly. All testing feels like redundant work – both in code and in code books – but I like the security of knowing that when readers finally work through the book every example has been thoroughly checked – and can easily be checked again when a query comes up.
The first signs began to come back this week that using git and vagrant were good choices. Tech editor Paul has begun feeding back using Github – and he has successfully run the vagrant installer. That means he’s automatically won the bleeding edge PHP the book needs, and a whole bunch of tools. That said, though, next week we may find (spoiler: we will) that not everything is quite as simple and bug free as might be hoped.
There are no new features to discuss this week – not because there are none associated with Chapter 4 but because the focus of this work has been to kick the existing words and code into shape.
Well that’s the overview – read on for the blow by blow.
22/06/2020 - Monday
Kicking off this week with a failure. Last week diary is not going out today.
More Chapter 4. Mainly extending tests so that they do more than just print. Also found that a bunch of examples in the Traits section aren’t in the chapter. These were probably cut in order to deal with repetition – but I think some sense is lost. Added back in the examples and wrote linking text.
Heard from Paul that his vagrant up ran OK - but he’s not looked in detail yet.
23/06/2020 - Tuesday
Churning through traits. Hunting down skipped listings – because in order to run a renumber, I’ll need to make sure the slots in the chapter match up with the alphanumerically sorted listings. Luckily, git will tell me if my listings fall out of order.. when I run a renum the only thing that should change in the chapter should be listing labels.
24/06/2020 - Wednesday
More churning through traits. Again many skipped listings – the absence of some of these seems to degrade sense a little so where necessary I have reintroduced the examples. Rewriting all tests so they at least do a simple value check and don’t just output by default.
25/06/2020 - Thursday
Moved into the section on late static bindings. My current strategy is to fix the chapter as is – and then circle back for additions. Once again, a few cut listings reintroduced and tests which only output now amended to suppress output and check values.
26/06/2020 - Friday
Finished late late static bindings – shifted into exceptions – tests written etc. It’s slow going and will have to consider at some point whether I can afford to write this many tests – or at least look for a more automated solution.
28/06/2020 - Saturday
Exceptions ongoing – more tests, more slow progress. Deadline for this chapter is Wednesday 1 July – I am beginning to think it may become necessary to work in accelerated mode and then backfill tests. Possibly also do a full day this weekend.
LATER: Suitably concerned, I pushed on and finished exceptions after all. I think a clean pass of Chapter 4 will be needed tomorrow in order to get this delivered without panic or lateness.
28/06/2020 - Sunday
Pushed forward today. Covered interceptor methods, final classes and methods, built-in Error object. More tests.
Also Paul checked in and started feeding back on Chapter 3. There is an issue where I seem to have confused scope and access – and some question as to whether PHP Codesniffer will handle PHP 8. Also my setup provision script failed to install some files for him because in my shift from linking to copying (to support Windows) I refused to clobber. I fixed that by setting the clobber flag, since that was the link behaviour in any case. It’s after 11 so I’m calling it.
