Things That Matter Most

Things That Matter Most

Credit Where It’s Due

by

Several years ago, I worked at a creative consulting agency that focused on brand strategy and naming for organizations both large and small. Our clients were local non-profits, regional medical centers, multinational technology companies, and all sorts of enterprises in between.

We worked often behind the scenes, building style guides and brand scorecards and nomenclature recommendations that were all later white-labeled by our clients. It was the kind of job where placing a finished piece in your portfolio felt a little disingenuous as, at the end of the day, it had someone else’s name on it.

We were like corporate ghost writers.

Sometimes, though, the projects we worked on required skills outside our areas of expertise. For these projects we hired out to other create firms, subsequently white-labeled their work, and passed things on to the client. I felt a bit guilty as I saw companies like Honda take full and complete credit not only for our work, but for our vendor’s work as well. 1

Once, while working with a large, multinational computing firm I saw a marketing director take credit for a naming idea I had proposed in a team meeting. Their product (currently) wields just shy of 20% of their market. I never wanted individual credit, but having some sort of credit for my team would have helped sooth the launch of their product.

Why Give Credit

There is no worse a feeling than giving your time, sacrificing weekends, compromising time with family, and running yourself into the ground on a project than watching someone else stand up and take credit for your work.

I have worked on teams where we’ve white labeled vendor work before passing it along – we’ve still given them credit in the footnotes of the project, but their name isn’t on the finished product. I’ve worked on teams where clients have white labeled our work before publishing it – often we’ve still gotten credit in project footnotes, readmes, or internal presentations about the project.

I’ve also worked on teams where clients have both white labeled our work and taken sole credit for the project in public. These are the kinds of clients who I’ll never work with again and, if asked for references, will actively condemn partnership with them.

I am very protective of my team. If I ask a team member to sacrifice their evening, or give up their weekend, or take a phone call while they’re on vacation it’s because I truly believe in the quality of the project and that their contribution is vital to its completion. 2 I’ll give them all the credit in the world internally, and also let the client know what lengths we have to go on their behalf because we believe in and value the relationship.

At the end of the day, all I’m expecting is acknowledgment of my team’s contributions. No co-branding, no press releases, no outrageous publish statements. Just when you or your team call out your own contributions, mention the external teams that backed you up and helped drive things through to completion.

Notes:

  1. Particularly when I later saw members of their internal design team use said work as part of their portfolios when applying for and getting jobs in the future. ↩
  2. Note: The times I make such requests from team members are extremely rare and only happen when I’m also giving up personal time and weekends and whatnot. I will never make a request of a team member I’m unwilling to fulfill myself. ↩

PHP: Read Only Attributes

by

Just like in JavaScript, many PHP developers find themselves in situations that warrant read-only properties. Unfortunately, the most common practice is to use a pseudo getter (again, like JavaScript) that’s more hack than it is design.

Again, I’m talking about things like $object->getProperty(), which works, but is poor design.

Like its JavaScript cousin, you’ve probably come across an object that looks something like this:

<?php
/**
 * Represent a used car.
 */
class Car {
  protected $odometer = 0;

  /**
   * Increment the odometer
   *
   * @param float $miles
   */
  public function drive( $miles ) {
    $this->odometer += abs( $miles );
  }

  /**
   * Get a protected odometer reading
   *
   * @return float
   */
  public function getOdometer() {
    return $this->odometer;
  }
}

$subaru = new Car();
$subaru->drive( 500 );
echo $subaru->getOdometer(); // 500

Like the JavaScript equivalent, this works, but it’s an ugly, unituitive hack. Don’t use this.

The Alternative

If you have build a class in PHP 5, you’ve used what’s called a “magic method” – namely, __construct(). A magic method is one that’s not directly exposed on an object instance, but which is invoked in certain specific situations instead. For example, invoking new Car() would invoke Car::__construct() if such a method exists.

As it so happens, PHP includes magic methods for both getters and setters of properties. Build these into your objects, and you can completely control the behavior of certain properties.

The code below is the same as before, but refactored to expose a read-only property on our object:

<?php
/**
 * Represent a used car.
 *
 * @property-read float $odometer
 */
class Car {
  protected $odometer = 0;

  /**
   * Increment the odometer
   *
   * @param float $miles
   */
  public function drive( $miles ) {
    $this->odometer += abs( $miles );
  }

  /**
   * Magic getter for our object.
   *
   * @param string $field
   *
   * @throws Exception Throws an exception if the field is invalid.
   *
   * @return mixed
   */
  public function __get( $field ) {
    switch( $field ) {
      case 'odometer':
        return $this->odometer;
      default:
        throw new Exception( 'Invalid property: ' . $field );
    }
  }
}

$subaru = new Car();
$subaru->drive( 500 );
echo $subaru->odometer; // 500
$subaru->odometer = 0;  // Fatal error: Cannot access protected property
echo $subaru->odometer; // 500

The @property-read annotation in our class’ docblock will tell your IDE that the class has a read-only property. If you depend on things like inline autocomplete, this added documentation can be a lifesaver during development!

Other Uses

Magic getters and setters can also help adjust an object’s internal state when properties are read or set. As I noted in the JavaScript walkthrough yesterday, this is an extremely rare use case and obscures the functionality of your object and application. Don’t use it unless you know exactly what you’re doing and understand the potential consequences:

<?php
/**
 * Represent an elementary particle.
 *
 * @property-read array $position
 * @property-read int   $speed
 */
class Fermion {
  protected $position = array( 50, 35 );

  protected $speed = 75;

  /**
   * Magic getter for an elementary particle that
   * obeys the Heisenburg Uncertainty Principle.
   *
   * @param string $field
   *
   * @throws Exception
   *
   * @return mixed
   */
  public function __get( $field ) {
    switch( $field ) {
      case 'position':
        unset( $this->speed );

        return implode( ',', $this->position );
      case 'speed':
        unset( $this->position);

        return $this->speed;
      default:
        throw new Exception( 'Invalid property: ' . $field );
    }
  }
}

$electron = new Fermion();
echo $electron->position; // 50,35
echo $electron->speed;    // Warning: Undefined property

$electron = new Fermion();
echo $electron->speed;    // 75
echo $electron->position; // Warning: Undefined property

JavaScript: Read Only Attributes

by

Every now and then, I come across a coding pattern that’s more hack than it is design. One that I despise the most is the use of pseudo read-only properties in JavaScript.

At some point in your coding career, you’ve probably seen a method masquerading as a property. I’m talking about things like object.get_property(). It works, but it’s a method call, not a real property.

The code to set up an object like this would probably look something like:

/**
 * Represent a used car.
 *
 * @constructor
 */
function Car() {
  var SELF = this,
      odometer = 0;

  /**
   * Increment the odometer
   *
   * @param {Number} miles
   */
  SELF.drive = function( miles ) {
    odometer += Math.abs( miles );
  };

  /**
   * Get a protected odometer reading
   *
   * @return {Number}
   */
  SELF.get_odometer = function() {
    return odometer;
  };
}

var subaru = new Car();
subaru.drive( 500 );
subaru.get_odometer(); // 500

Again, it works, but it’s a hack. It’s ugly code. It’s unintuitive.  It has no place in a well-structured application.

The Problem

Code should be somewhat self-documenting. Object methods and properties should be clearly named in such a way that developers will immediately know what the method does and the object contains. When methods are used as accessors for properties, objects become that much more cryptic to the next developer that comes along.

Functions like get_data() make sense – it’s a function that retrieves (and possibly returns) information. On an object, methods like object.save_data() make sense – it’s a function that saves (possibly to an external data store) some piece of information.

Properties like object.name are static things. They’re properties of the object, not functionality that should be invoked. At times, though, properties need to be read-only (i.e. exposing the status of a database connection) and that can be a confusing scenario in vanilla JavaScript. The easiest way is to use the hack above to hide the variable itself within a closure and make it read-only through an accessor method.

But this method begins to look like the data manipulation methods referenced above, forcing new developers to look deeper at the code to figure out what’s going on. Making the person who has to support your code think is a bad idea; particularly if they expect your code to “just work.”

The Solution

Thanks to ECMAScript 5, you can now programatically define the properties of your objects. This means you can define a property that has a getter – allowing you to read object.property directly – but that lacks a setter – triggering an error when attempting to set object.property.

The code below is the same as before, but refactored to expose a read-only property on our object:

/**
 * Represent a used car.
 *
 * @constructor
 */
function Car() {
  var SELF = this,
      _odometer = 0;

  /**
   * Increment the odometer
   *
   * @param {Number} miles
   */
  SELF.drive = function( miles ) {
    _odometer += Math.abs( miles );
  };

  /**
   * Get a protected odometer reading
   *
   * @return {Number}
   */
  Object.defineProperties( this, {
    "odometer": {
      "get": function() { return _odometer; }
    }
  } );
}

var subaru = new Car();
subaru.drive( 500 );
subaru.odometer;     // 500
subaru.odometer = 0; // does nothing
subaru.odometer;     // 500

Other Uses

Another edge case that defined getters and setters satisfies is when setting a property must update an object’s internal state. This is a rare use case and obscures the functionality of your application. Be very careful using anything that looks like the code below:

/**
 * Represent an elementary particle.
 *
 * @constructor
 */
function Fermion() {
  var SELF = this,
      _position = [100, 200],
      _speed    = 50;

  /**
   * Get the particle's position
   *
   * @return {Array}
   */
  Object.defineProperties( this, {
    "position": {
      "get": function() {
        _speed = undefined;

        return _position;
      }
    }
  } );

  /**
   * Get the particle's current speed
   *
   * @return {Number}
   */
  Object.defineProperties( this, {
    "speed": {
      "get": function() {
        _position = undefined;

        return _speed;
      }
    }
  } );
}

var electron = new Fermion();
electron.position; // [100, 200]
electron.speed;    // Undefined

electron = new Fermion();
electron.speed;    // 50
electron.position; // Undefined