Is Your Program a Product?

When you write a program, whom are you writing it for?

Stupid question? Your boss. Or maybe the customer.

WRONG, BUCKO. You’re writing it for other programmers.

“Who are these other programmers?” you ask, eyes full of wonder, young hopper as you are.  They’re your team mates. They’re your future hires. They’re you six months from now, when you can’t remember what the hell you were thinking when you wrote this code right here.

fred

This idea is from Fred Books, one of  my heroes and whom, were it somehow possible, I would take as my lovely brogrammer bride, in his timeless classic The Mythical Man Month. (OK, maybe it’s not “timeless;” you could probably use email today rather than his recommended “telephone log.” But every other chapter is pure, modern-day-relevant gold.)

You Don’t Want Just a Program

A program, by ol’ Fredder’s definition, just does the job it’s supposed to do today. It’s something you cranked out as quickly as possible to get working ASAP before moving on to something else. You will never, ever understand it tomorrow. Neither will the guy who inherits it; he’ll make an impassioned plea to your boss to throw it out and start over. Where the Still Drinking guy wrote in his famous Programming Sucks essay:

“…everybody spends half their time coping with the fact that nothing matches anything or makes any sense and might break at any time and we just try to cover it up and hope no one notices.”

…he’s talking about your humble “program.”

You Want a Programming Product

A programming product, on the other hand, is well-thought-out. One can look at the code and… understand it. Not because you’ve dumbed it down and avoided cleverness, but because you’ve written it clearly.  You don’t have variables named “x” or “count”. You don’t drag the reader into callback hell.

It doesn’t rely on memory, yours or your team mates’.  It doesn’t require one to go digging through the codebase to find out WTF is going on before they can even make use of existing functionality.  Stuff like this can not be going on.  It can be used and extended by anyone who knows the underlying philosophies of this project.  (OOP?  MVC?  ABC, BBD, yeeeeeaaaaaaaaaaAAAAaahhhhh?)

Ol’ Freddie, he estimates that ensuring your codebase is also a product for other developers takes three times the effort as just phoning in an aforementioned “program.”

Probably You Have a Programming System

When your program actually consists of multiple pieces that have to function together, you’ve actually got a programming system.  Does your website or mobile app rely on a back-end API?  Do you have to coordinate with the unfortunately-titled “back end developer(s)” to hammer out a contract  of what that JSON is going to look like?  Of course you do; it’s 2016.  You’ve got a programming system.

You already know what this entails.  The API guys can’t just go changing things willy-nilly, no matter how much of an improvement it might be, because there are apps out there in the wild relying on it.  You can (and should) do API versioning, but that brings a whole ‘nother level of complexity with it.

If you’re on the client side, does it mean you model your data to match what the server gives you?  That’s easy, you can map the JSON response from the API to your own objects automatically! But those objects might not fit your app exactly, and introduce awkwardness.  On the other hand, you can translate the data from the server to your own data model.  It’s more efficient, but also more work.

Oh, the quandaries for a programming system!

This is so common today that I don’t even have to tell you.  It brings complexity.  (Brookie BTW estimates a 3X increase in effort for this one too.)

A Programming Systems Product is What You Need

You can probably guess what this one is already, you rocket scientist you!  The programming system you need, but with every part of it done up as a product you’d be proud to pass off to the guy sitting next to you.  A collection of projects and codebases so well done that nobody would ever dream of suggesting it be thrown out and started again from scratch.  (Or at least, nobody would ever be able to justify it.)

This is the “intended product,” but if you’ve done the math, it takes 9X more resources than cranking out some unintelligible mess this afternoon.    (Actually, given the astronomical cost of programmers these days relative to the 1970s, when they were probably seen more like accountants, the price tag is probably a lot more than 9X.  Which is why you’ve never worked somewhere that actually allowed you to do this.)

Here’s an illustrative chart I drew on the bank of a bank statement, for the sake of having graphics in this blog post:

chart

I like to think I drew that from my own brain, but in fact, I think I mentally swiped it straight from The Mythical Man Month. (Other than the smileys, I mean.  Fred Brooks, if you’re reading, I’m sorry. Call me, K??)

Posted in Programming | Leave a comment

Tired of waiting for an RPM of MonoDevelop 4.0?

So was I, so I decided to build it on Fedora 18.

Unfortunately, building MonoDevelop from scratch turned out to be a bit of a nightmare. So when I finally got it, I created a script to to it.

See script comments for frustration.

https://bitbucket.org/seanmccleary/monodevelop4-fedora-install

Posted in Uncategorized | Leave a comment

3 Signs Your Object-Oriented PHP Is Slowing Down Your Team

In the last few versions of PHP, their OOP got real.  And this is good.  While it’s not the perfect paradigm, I am a big fan of object-oriented programming.

One of the key concepts in object-oriented programming is interface.  It’s about you and another programmer having an agreed-upon way for your code to talk to theirs.  Having small, componentized software with clearly-defined interfaces is great for teams.  It’s what’s made OO the dominant paradigm in business since the 1990s.

Unfortunately, too much PHP code these days follows the letter of the OO law, but not the spirit.  If you’re making any of the following common mistakes, you’re costing the rest of your team valuable development time.

  • Does your method return an array where the calling code is expected to just know the keys it will contain? Yes? Make it a class.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    
        // BAD - Calling code has NO IDEA what's in the returned array
        public function getPerson($id) {
            $person = array(
              'name' => 'Sean',
              'age' => 33,
              'favoriteColor' => 'blue'
            );
            return $person;
        }
     
        // GOOD: Calling code knows about the Person class
        public function getPerson($id) {
            $person = new Person;
            $person->name = 'Sean';
            $person->age = 33;
            $person->favoriteColor = 'blue';
            return $person;
        }
  • Does your method take, as a parameter, an array where the calling code is expected to just know what keys it populate? Yes?  Break it up into separate parameters.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    
                // BAD - Calling code does not know what $student must contain
                public function findStudent($student) {
                    $person = new Person;
                    $person->name = $student['name'];
                    // ...
                }
     
                // GOOD - Calling code knows exactly what to pass
                public function findStudent($name, $age) {
                    $person = new Person;
                    $person->name = $name;
                    // ...
                }
  • Does your class have one single private member which is an array?  Why do you hate the guy who will have to inherit this code?  Break it up into individual private members.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    
                    // BAD - Anyone maintaining this in the future has to study 
                    // the WHOLE CLASS to see what array indexes are in use before
                    // making changes
                    class Person
                    {
                        private $_data = array();
     
                        public function __construct($name, $age) {
                            $this->_data['name'] = $name;
                            $this->_data['age'] = $age;
                        }
                    }
     
                    // GOOD - It's clear at a glance what class members are in play
                    class Person
                    {
                        private $_name;
                        private $_age;
     
                        public function __construct($name, $age) {
                            $this->name = $name;
                            $this->age = $age;
                        }
                    }

For some reason — reasons I do not understand — some PHP developers (just spend a little time on /r/php) are vehemently opposed to writing interfaces.  ”Write a class just to use as a return type?? This isn’t Java, with their labyrinthine class library!”

Well, no, it’s not Java.  But just writing classes to provide interface to facilitate teamwork won’t turn it into Java’s ridiculousness, either.  That’s a false dichotomy.

The takeaway: Other coders should never have to dig through your implementation to figure out how to work with your code.  They should have access to an interface (either in the form of a class, or literally just an interface) to tell them everything they need to know.  It’ll cut down on bugs, and save significant development time over the lifespan of a project.

Posted in Uncategorized | 1 Comment

Property Accessors using Traits in PHP 5.4

When you first wrote your PHP application, your Customer class just had a fullName property, and all was good.  ”Hi there, <?= $customer->fullName ?>!” your code gleefully outputs at the top of every page.

Then one day your boss decides that that’s too formal for a hip young company such as the one you work at, and what you should be going is greeting the user by his first name.  After a bit of a refactor, your Customer class now has two separate properties: firstName and lastName.

You change the header of your site to just use $customer->firstName now, but what about the rest of the codebase? There are a lot of places where you were using the customer’s full name, which should continue to use the full name. Should you change them all to a concatenation of the two new properties? You could, but you probably don’t want to.

More important, the guys who work on the corporate intranet use the Customer class, too.  They’re going to be annoyed, to say the least, if you tell them you’ve removed a property from that class on which they rely heavily. And rightly so, because it’d be breaking the interface you gave them.

Wouldn’t it be nice if there was some way in PHP to keep the old fullName property as a kind of alias, which just concatenates the two new properties?[1]

In other languages, you can.  In C#, it’d look like this:

public string FullName
{
    get
    {
        return firstName + " " + lastName;
    }
}

(Something similar was proposed for PHP 5.5, but unfortunately it was voted down.)[2]

Luckily, adding this functionally is really pretty easy using PHP’s overloading (which, in true PHP fashion, is not overloading in the sense that every other language on the planet uses the word “overloading”).

So let’s take a look at how.  (If you want to cut right to the chase, I’ve got an implementation available on bitbucket.)  Let’s implement it as a PHP trait, so it doesn’t interfere with your own class hierarchy:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
trait AccessorsTrait
{
    public function __set($name, $value) {
        $accessorMethodName = 'set' . ucfirst($name);
        if (method_exists($this, $accessorMethodName)) {
            call_user_func([$this, $accessorMethodName], $value);
        }
        else {
            $this->{$name} = $value; // Fall back to default behavior.
        }
    }
 
    public function __get($name) {
        $accessorMethodName = 'get' . ucfirst($name);
        if (method_exists($this, $accessorMethodName)) {
            return call_user_func([$this, $accessorMethodName]);
        }
        else {
            return $this->{$name}; // Will trigger a PHP "Undefined property" notice
        }
    }
}

(The __get and __set methods are only called if the property being accessed doesn’t exist.)

The above code checks to see if an appropriate accessor method exists for the property you’re trying to get or set.  If so, it invokes it. If not, it just falls back to the standard PHP behavior of triggering an E_NOTICE when trying to read a non-existent property, or creating it when trying to write to one.

Now back to the example of your Customer class. Apply the above trait like so:

class Customer 
{
    use AccessorsTrait;
 
    public $firstName;
 
    public $lastName;
 
    public function getFullName()
    {
        return $this->firstName . ' ' . $this->lastName;
    }
}

This allows you to continue using $customer->fullName in your calling code.  And interface is maintained.

Posted in Programming | 1 Comment

New Open Source Projct – MVC Basics

After getting sick of copying the same basic functionality into each new ASP.NET MVC 3 project, I ripped it out and put it into a separate easy-to-use package called Sean’s MVC Basics.

Right now it’s got three modules (separated using MVC “Areas”):

1. Analytics, to include all the meta tags needed for Google Analytics, Bing Webmaster Tools, and Yahoo Site Explorer.

2. CDN, to easily toggle between using locally-hosted JavaScript, or JavaScript hosted on Microsoft’s CDN.

3. The biggie: A drop-in replacement login page which only uses OpenID & OAuth providers — NO local usernames or passwords!

Packaging up the little things I use like this and making them open source is still pretty new to me, so if you do use it, I’d be thrilled to hear about it, and if you have any feedback or want to contribute, by all means let me know!

Posted in Internet, Programming, Web | Leave a comment

Too Many Sean McClearys On The Dance Floor

Just look at this guy at the 35-second mark…

Not only is he also a websman; not only is he also from Oregon; but he also has my haircut!

Posted in Personal | Leave a comment

More On the Crapping Up of Twitter: I Am Not Alone

Scott Vandehey seems to agree with my (according to feedback I got) charming, popular opinion on the futility of trying to attach any kind of meaningful meaning to the number of your Twitter followers.  In his post he calls it “The False Economics of Twitter.”

It’s nice to see I’m not the only one who believes Twitter was designed with the intention that you follow people whose tweets you actually want to read[1] and is confused by the oft-espoused assertions to the contrary.

Posted in Internet, Opinion, Web | Leave a comment

Forget “Reach” For Measuring Social Media ROI (At Least Until It’s Actually Measurable)

A hand reaching toward the sky

Photo by Twitter user Charl22

HubSpot recently wrote that “reach” (your number of Twitter followers and Facebook “likes”) is the number 1 way to measure social media ROI, saying:

The number of Twitter followers, Facebook fans, LinkedIn group members, etc. you have is directly related to your social media success.

Perhaps the folks at HubSpot haven’t had much time to look at Twitter lately. (They do seem to be busy writing whitepaper after fact-heavy whitepaper[1]; they have so much to share with us.)

I wish they would have expanded on this.[2] Because I find it hard to believe.

Twitter: Follow Me (Blindly)

The thing is, Twitter is full of accounts who follow other people with no intention of ever reading their tweets, ever.[3] Many are powered by programs which automatically follow anyone deemed to be part of their target audience (usually determined by whom they’re already following), or just indiscriminately follow everyone, blasting the follow-shotgun drunkenly around in all directions. The thing is: They don’t care about you or your tweets; they’re only hoping you’ll follow them back so they can do one or all of the following:

  1. Advertise to you.
  2. Appear to be some kind of Twitter big shot with oh-so-many followers.
  3. Sell the account, with its 10,000 followers, to someone else. (Yes, these services exist. I’m not linking to them.)

There’s also no shortage of people who do this manually, over time — people who follow thousands of other users. There are not even enough hours in the day for them to read what their followers tweet.

I’m not saying there’s anything wrong with following a gazillion people on Twitter, or that it’s misusing the service. What I’m saying is: obviously, many many Tweets go unread, and that fact does not jive with a belief in an ROI-predictive “reach” which is based on a number of followers. [4]

Facebook: You Really Like Me?

Like us on Facebook, and get this coupon! When we reach 3000 likes, we’ll donate to this charity!

How many Facebook campaigns attempt to motivate people to like them for reasons other than actually liking their product or service? (Many, from what I’ve seen.)

Is there a good chance this person is going to want to chat with you and other passionate users about, let’s say, mountain bikes (yeah, your company sells mountain bikes) once they’ve clicked whatever they had to click to get their Starbucks coupon?

Because, if not … well, how is this more valuable than just buying a big list of email addresses from some shady company, and firing up the spam cannon?

Give me a big stack of coupons, or freemiums[5], or funny kitty videos, and I’ll give you a big stack of Facebook “likes.” Even if you’re giving away something relevant to your business, all the “likes” in the world won’t mean anything if the people don’t actually, you know, like you.  It does not mean all your future updates and messages will “reach” them It only means you’ve paid, in time or money, to get their attention for a few seconds: a convoluted, expensive advertisement.

Can We Get Around Reach, Please?

Followers and “likes” are not true measurements of reach. A company with 500 followers, 50% of whom are engaged and interested in their product, has more reach than one with 10,000 followers where only 1% are interested.  And how many of each company’s followers are computer programs? Self-promoters just looking for a follow-back? Imaginary hot chicks “lookin’ for cool people lolz”?

“Reach” in the sense the word is being tossed around is actually how many people theoretically could have seen your message. (And by all appearances, quite a few people didn’t.)  It’s not a useful metric; it will not help you determine whether you’re wasting your time not.[6]

Anyone who dedicates time and resources to “focusing more of your social media efforts on generating new fans and followers,” as HubSpot recommends, should first ask them (or anyone else, for that matter) to connect the dots and show the causation (not correlation) between more social network pals and success.  My fear is that it actually works in reverse, and that fans and followers are not the cause of successful social media use, but can be a result of it.

But then, I’m not a marketer, so by all means: set me straight.

PS[7] – Sorry about all the footnotes!  I just re-read A Supposedly Fun Thing I’ll Never Do Again and it must have had an effect!

Posted in Internet, Opinion | 5 Comments

Where’s Sean Been?

All quiet on the blog front lately.  So where’ve I been?  Well, I moved to Austin for a project I’m working on called Common Tastes.  It’s a recommendation engine for anything and everything, which we can apply to niche-targeted websites on any subject, like beer, tea, fast food, video games, etc.

Check it out, and by all means, if you have any feedback, please let us know!

P.S. – See that little doodad over there on the right, saying “People who like this blog will love this blog?”  That’s the Common Tastes Predictor Widget, in case you’re curious.

Posted in Personal | Leave a comment

3 Tips for Effective Web Writing

Web writing is a genre of its own, and one day universities will offer degrees in it just like they do for journalism. (In fact, some probably do already.) Half way between newspaper and brochure writing, copy for the web must both inform the user and present a professional appearance.

Unfortunately, most people writing for the web today tend toward one spectrum or the other. Jakob Nielsen, from whom most of the information in this article originates, is the master of usability and his website is just as easy to use and navigate as you’d expect; but find me one company out there with a website design as bland as his and I’ll show you a soon-to-be-out-of-business company.

Similarly, websites with giant mastheads, lengthy introductory text and useless start pages are sadly a dime a dozen.

What’s proven is this: You only have a split second to snag a web user, and users don’t read; they scan.

Simple to grasp, yet so often forgotten.

#1. Know Your Users

Your users are doing one of two things on your site: Seeking or browsing.

The Seeker

If your website is a resource, then your website is for seekers.  And for the seeker, you need to step back and get out of their way.

Do not put three paragraphs of bland marketing copy between the seekers and what they’re looking for. Seekers have no patience, and, unless you’re the only game in town, will keep on surfing to the first one of your competitors that doesn’t make them think* in order to get what they want.

Don’t worry about your page looking too skeletal. Think back to the early days of search engines, when there were more contenders out there. Who emerged as the leader? The ones who surrounded their search forms with a bunch of extra content they wanted you to look at? Or the one with one simple input field and a button?

The Browser

Browsers are users you’ve drawn to your site and now that they’re here you need to tell them something. Maybe it’s your latest promotion. Maybe it’s this list of funny links.

Unlike with the seeker, instead of stepping back and getting out of the way, you need to get the the browser’s attention; the text is the focus. Put the important words in the F-pattern zone where they’ll see it. Start sentences with key words that will jump out at them.

In either case, dense blocks of text copied from your brochure about how you’re the #1 provider of such-and-such neither helps them find what they’re looking for nor tells them anything they care about.  It will only lose them in a hurry.

#2. Use Bullets For Scannable Text

Ever notice that so many web pages and blog entries are titled “7 Ways To Do This” or “5 Tips For Doing That”? It’s because readers will expect a bulleted list. And the readers? They like their bulleted lists.

Why? First of all, the user knows it’s likely to be a short article, and is therefore more likely to check it out.

And bulleted lists make it easier to get the gist of the text without having to invest the time in actually reading it all.

#3. Make Your Paragraphs Shorter

Ever notice how newspaper paragraphs consist of only a single sentence? They’re not dumbing it down. Newspapers have dealt with readers scanning their text to find the interesting stuff for years.

I’m not saying a single sentence is the maximum, but do make your paragraphs more specifically-themed than you would for your term paper.  Readers guess from the first couple of words what to expect if they continue reading, and decide in an instant whether or not they’re interested. Having each idea stand out visually makes it easier to jump to the next one, and the text faster to scan.

* Don’t Make Me Think by Steve Krug, by the way, has made such an impact on me that I now inadvertently work its title into discussions about web usability.

Posted in Internet, Web | Leave a comment