Notes on "Notes to Myself on Software Engineering"

I just finished reading an excellent article about software development over on Medium by François Chollet entitled "Notes to Myself on Software Engineering."

The whole article is pretty good, but I wanted to point out a couple of highlights that, in my humble opinion, stand out from the rest.

In the section regarding APIs, under item number 4, Chollet writes:

"If the cognitive load of a workflow is sufficiently low, it should be possible for a user to go through it from memory (without looking up a tutorial or documentation) after having done it once or twice."

This is one of the most important points about API design that gets lost in the shuffle for an API to "do everything." A well-designed API is, on its face, simple. If you're looking to make a useful thing, you have to also make it easy to use. This is the kind of insight that a Lead should have cross-stitched and framed for their desk.

Item 4 under "On Development" also speaks to this point, generally:

It’s okay to say no — just because someone asks for a feature doesn’t mean you should do it. Every feature has a cost that goes beyond the initial implementation: maintenance cost, documentation cost, and cognitive cost for your users. Always ask: Should we really do this? Often, the answer is simply no.

Too often we find ourselves building one-off features that aren't really necessary in places where they don't really belong. These features increase the cognitive load on a user, mess up our well thought-out solutions, and dirty up our code. (They also have a weird tendency to do the exact same thing on the API side.) This is especially true for programmers like me who have spent large amounts of our career producing products for the specific internal use-cases of our individual companies.

I'd also like to draw attention to Item 3 under the same heading:

Taste applies to code, too. Taste is a constraint-satisfaction process regularized by a desire for simplicity. Keep a bias toward simplicity.

One of the things I use in code review to pick out pieces where a dev should have refactored is the length of a method. A method that runs for 1,000 lines is likely 900 lines too long, but a method that's 175 lines might be just fine. That "gut" sensation about something that is eventually going to cause a problem is an important part of the process, and I find the idea of identifying it as "taste" more pleasant than "code smell."

Taken together, I think these three items remind us to keep both the user and our future selves in mind when making decisions that effect the complexity and composition of our code and the systems it builds. They press towards simplicity and ease of use. And that is something very much worth keeping in mind as we go forward.

The rest of Chollet's article is full of other tidbits of wisdom that we, as devs, should keep in mind. And I encourage you to read the rest of it at Medium.


Tips and Tricks for Wordpress Development

Recently, I had the pleasure of onboarding a few PHP Developers into an environment that included (amongst other things) several Wordpress instances. To my surprise, none of these devs had ever worked in Wordpress. (I may be dating myself here but Wordpress skills were, at one time, the skills for a PHP developer.)

During that onboarding process I ran into three old tricks I've been using for WP Development forever that were both extremely helpful and surprising to my new devs. They are presented here for anyone else who hasn't stumbled onto them yet.

1. Symlinking the Themes, Plugins, or Even WP-Content

In a perfect world, you'd only ever have to write code for the most recent version of Wordpress. But we don't live in a perfect world. If you're in a mixed environment where every WP instance isn't kept completely up-to-date, or if you're building a plugin or theme for public consumption, you have to be able to test on multiple versions of WP.

To do this, I like to install my Wordpress code in its own folder inside of my VM shared folder, marked by version, and setup a vhost to access that particular version, like wp495.loc and wp496.loc. Then, I pull my theme or plugin from the central repo into an adjacent folder. After that, I simply create a symbolic link from the appropriate place in wp-content to the repository…

 

 

Now, you can symlink the code your working on into multiple WP installs (and versions) for testing without having to copy and paste or push and pull every time you want to run tests.

One caveat here: if you're on Windows (like me) you'll want to be running Git Bash as an administrator when you start the box to ensure this all works properly.

2. Use wp-config.php to Override Site URL

You can use the wp-config.php file to override the home and siteurl settings that are part of the wp-config database. These are the configuration options that cause Wordpress to redirect you back to the production url when you first dump a db to your local. The override is simple:

These values make it easier to manage database updates. You could even use them to work directly with the production DB (if you don't like your job all that much), or store your DB copy up on the actual database server. It's significantly faster to copy the database on the server than dump and re-constitute it on local. If you're going to do that, you just need to adjust the DB values in the same file.

3. Forget About the FTP Server

If you want to be able to use Wordpress' features like Media Upload and Update on the server, then you're going to have to setup an ftp server. And most of your clients are going to need that. But, if you're building, say, a personal wedding website, then you don't need to bother.

Instead, install a good Amazon S3 plugin like WP Offload S3 Lite and setup your local instance to use it. Then, add your media on the local machine. The plugin will automatically move the media over to S3, and set the URL for the media to the S3 url.

If you're keeping the rest of you WP content folder in CVS (not recommended for large, long-term projects) then updating themes or plugins is just as simple. Simply run it local while connected to the production database, commit, and pull on prod.


Agile Probably Won't Solve Your Problems

The Agile process has been a boon to the software industry. Whether you're building the next generation of cutting edge IoT devices, a desktop-bound accounting application, or next year's killer app, Agile gives you an advantage. It's flexible, and gives teams a way to talk about the process of building complex things.

Recently, according to an Agilist consulting friend of mine, it's come into vogue to implement these processes in other business areas. Marketing, sales, support--even distribution--is working to implement this strategy. These efforts, he reports to me over the watery half of an Old Fashioned, have met with mixed results.

There's a very simple reason for that, of course. Agile probably won't solve your problems.

Executives have a problem in that they keep looking for a magic bullet. They believe hype more than substance. Agile excels at taming the kinds of troubles that have long plagued teams of software developers--planning problems. But that's a problem of highly specialized, precisely trained people. It's the kind of problem engineers and legalists and E.R. physicians face.

It's likely not the problem that's bothering your salesforce.

The troubles you're probably having in most of your departments aren't based off planning. They're problems of execution. They're teams with ineffective leaders; staff that's unconnected to the work; and managers who only care about results so far as they affect their bonuses. They are--in short--business problems. They are the same business problems that have been causing trouble in business since the first founder hired the first employee.

A quick read (you actually have to read it, btw, you can't just read the cover) of Harvard Business Review will help to set you straight. Business suffer mostly from a lack of communication. Agile, for all its strengths, can't solve that.

If you want to solve those problems you need to hire team leads who actually lead. You need to pay attention that managers are managing with care. They can't simply pay attention to strategy and execution. They also have to take that the people who execute it are capable to do it. Your organization needs to focus on the market. Both where the market is going and ideally, why. Those are the failures that are really slowing you down. They aren't the failures that a planning system fixes.

Unless you have a very specific problem--a failure to plan complex tasks well while maintaining flexibility--the Agile probably won't solve your problem.


Laravel Certification Begins Sales -- Is It Worth It?

Laravel Certification Opens to Early Bird Sales

This afternoon, the folks over at Laravel, LLC--the for profit branch of the Laravel organization--sent out an email to everyone who had signed up letting them know that "the Laravel Certification Program is now available for pre-order!" Otwell and company have set the price at just under €200 (presently, that's just shy of $240 US, for my fellow yankees.) At that price, it's in line with other similar certifications, although the quality of this one remains to be seen.

Another Certification Program?

I can hear the collective groan from here. Every time another one of these certification programs is whelped by its totally profit disinterested group, we go through the same debate. "Is the cert worth it?" or for that matter "Is any cert worth it?"

Ultimately, we bog down. One camp seems to put a magical faith in the certification that'll get them a better paying position without having to put in any actual time working to get there. The other camp insists that passing these certs proves nothing, and passionately argues that you might as well put your money in a pile and light it on fire. And anyone thinking about plunking down 200--ok, I don't know what's on the Euro note--let's say Frenchmen smoking cigarettes--200 Frenchmen Smokin' is left to scratch their heads and wonder about the state of their 401k.

So, Is It Worth It?

My answer here is pretty simple: it is worth the cash if you're doing it for the right reason. To me, a certification isn't something you get because you're hoping to start new programming career. It won't get you a job by itself.

I Look At Resumes

And I look at as many of them as I can find. Getting ahold of a capable (let alone competent) developer in the current space isn't easy. There's just not that many out there. And I abhor the idea that a C.S. degree qualifies one to write actual applications. (Full disclosure: I don't have one.) The things they're teaching Computer Science students in college simply aren't the things real-world programmers do everyday.

If a resume for a Jr. Dev came across my desk and that dev had zero experience, but was Laravel Certified, I'd likely still pass them over. The upside to these certs is when that resume is in a pile of 4 or 5 resumes with a similar level of experience. The certification suggests familiarity with the platform, and that familiarity is far less of a gamble then "I worked in it on and off for awhile."

It's Worth It, Because You're Competing

In the end, every job application is part of a competition, and we compete with the intent of winning. If the only jobs you'll ever apply for are the ones where your resume isn't in a pile, you probably don't need this certification. (I'm looking at you, Donald Trump Jr.) But if you're competing these certs do offer a competitive edge, especially with your less technical management set.

Have I bought the cert? Heck no. It's like $240, for Pete's sake. But if you're interested in moving forward, $240 is a small price to pay to stand out of a crowd.