Tag: stepwise refinement

As you may have already heard from me, I feel like I’ve made some significant progress in the quality of the code I am able to produce over the past few months. I haven’t written about it yet, as I’ve been exploring the specific implications and applications of what I’ve stumbled upon.

I’ve had a chance to tell a few new people about it yesterday, and again it’s hard to communicate the kind of benefit that I see potential for, and frankly, it’s hard for a person who has not seen it to believe it. So I’m hoping to be able to communicate to Josh Leuze, author of Meteor Slides, and to Reid and Peter – who, as I understand, both read the source code of The Events Calendar – some of the techniques through the source code of their systems.

Here’s the first example of code that implements some of these principles. I think the refactoring / diff format in which the examples are presented fit well with what I’m trying to communicate, which is basically a collection of changes to how code I commonly read is written. Here it goes:

https://github.com/dbernar1/Meteor-Slides/commit/93cd6b91fc72e8fb8d3413ae366a79af4bcee3c5 is a very good example of where a function is commented to express the functionality. I find it better to just simply name the function using those words – comments very often get out of date.

https://github.com/dbernar1/Meteor-Slides/commit/d80dab8c855a1d918c95d7aec8c64583e44df705 shows using a static variable for a value that is obtained from the database, and doesn’t change during the execution of a program. I like this in part because of use of the uncommon static keyword, in part because it enables removing duplication ( for cases such as when I want to change the option name ), and I find it is a nice way of encapsulating something that needs to get initialized once, like getting a database connection.

https://github.com/dbernar1/Meteor-Slides/commit/35fcb3ac1254bd290a44f4a75b3e8702eac181a9 shows a technique I use to name parameters to functions that take several parameters. Especially nice for naming those “true”/”false” parameters to functions that even the WordPress coding standard suggests trying to avoid. It says: “Since PHP doesn’t support named arguments…”, but I think this example proves otherwise. Of course, python-style named parameters, where order does not matter any more, do not exist in PHP, but it is entirely possible to name parameters to functions as I show there.

https://github.com/dbernar1/Meteor-Slides/commit/7bab45bb35760a7fa5827542a57c556ccbe66ddb is the meatiest example of the bunch. I could have done several smaller refactorings. I suggest reading it by reading the change to meteor-slides-plugin.php first. An important thing to note is that it would have been much easier to express the functionality with well-named function stubs, like the new version does, when originally writing the software. This is because it is easier to express the algorithm of using the overrides if they exist without at the same time having to think about what the implementation of “is this file overridden in the child theme” is. It is also easier to read, because it is in English, not in “WordPress”. It is also important to note how at least one level of implicit meaning has been replaced by explicit meaning, with naming functionality such as “if ( the_child_theme_has_overridden_css_for_meteor_slides() ) {“. I’ll leave you with that for now.

What do you think? I’d love to get feedback from other software developers.