Software Development isn’t Math — it’s Communication

Many software developers start their career by obtaining a degree in computer science or engineering. These degrees typically start with a very strong mathematical foundation but focus much less on written communication. This is a mistake!

Now, before I get a bunch of nasty comments telling me math is the most important thing in the world — let me explain. Software development obviously involves a significant amount of abstract analysis and requires the ability to understand mathematical and engineering concepts. Without these skills, we end up with brittle software that performs poorly..

But, my experience  has taught me these skills are only useful if a developer also has the ability to communicate their ideas effectively.

The most important skill for a software developer is the ability to communicate abstract concepts in concise, logical and structured ways

In case you missed it, the last half of the above statement is also a good definition of higher-order programming languages. We could still be writing code in 0’s and 1’s. But, we’re not — because it’s much more difficult to understand binary than higher-order languages. In fact, we even call them — wait for it — ‘languages’.

If a developer’s only intent was to communicate instructions to the computer / operating system — binary or machine code would be sufficient.

Whether they realize it or not, all developers are writing code for three audiences:

The Computer, the Developer and the Maintainer

I know, it sounds like a C.S. Lewis book. But, just like a good writer knows his audience, all developers should consider their audience as they design and write code.

For any given software program, there is an infinite number of ways to design a solution. How you make use of things like composition, polymorphism and other design patterns indicates to other developers and maintainers how you intend the system to be used, modified and extended.

Take a break, look at your code through someone else’s eyes

For any real, meaningful project, your code will never run in a vacuum. Someone is going to modify it. Someone is going to integrate with it. It’s not enough just to make it possible–you need to make it as easy as possible. Specifically, you need to make it easy to extend the right way — and hard to modify the wrong way.

What do you think? Have you known someone who came up with viable solutions that no-one could understand? Are communication skills vital for software developers?

 

A project template for WebPack + TypeScript (A.K.A. Framework Fragmentation Frags Developers)

hand grenade

wet-template

One of the wonderful things about the rise of open source is the corresponding increase in framework and library options.  One of the biggest disadvantages is the huge fragmentation caused by this increase in options.

If you’ve ever played a first-person shooter, you’re probably familiar with the term “fragging“.  Gamers frequently use this term, although it was coined during the Vietnam war to represent deliberate killing of an unpopular team-member.  The number of JavaScript library/framework combinations is staggering (26,000 listed on GitHub) and easily leads to developer brain implosion — hence the title: “Framework Fragmentation Frags Developers”.

dynamite

After researching numerous various options and prototyping with several different frameworks / libraries, languages and build tools (Babel, TypeScript, Grunt, Gulp, Bower,Webpack, Aurelia, React, ad infinitum), I’ve found what I consider to be the best (read most likely not to be dead/deprecated within 6 months).

Truthfully, this is a fairly minimalist solution as it allows me to customize each project easily.  It includes the following:

  • A testing framework (Mocha + Chai  — run-away community favorites)
  • Build scripts (NPM scripts are powerful, cross-platform and minimalist)
  • A bundler (Webpack -relatively easy, powerful, well-supported)
  • A linter (TypeScript — okay, this is more a language than a linter but close enough)
  • An initial project structure (it’s amazing how much time teams spend arguing about this)
  • VS Code bindings (An excellent, minimalist, hackable editor)

So, without further ado, here’s how to use the template:

  1. clone the wet-template repository (WEbpack + Typescript – ‘wet’, get it?)
  2. From a shell / command prompt do the following:
    1. ‘npm install -dev’
    2. ‘code .’
  3. Create a new git repo in a separate folder
  4. Copy everything except the .git folder into your new repo.
  5. Modify the package.json in this new folder to account for your git repo, description, keywords, author, etc.

Dude, where’s my code

wet-template folder structure
wet-template folder structure
  • src – All of your source code (TypeScript files) should be in the src folder.
  • test – Tests, surprisingly, are placed in the test folder (again, TypeScript here).
  • build – The TypeScript compiler places files that are compiled into JavaScript (by pressing ctrl+shift+B) in the build folder
  • dist – bundled (via webpack) JavaScript ready for distribution (e.g. via npm) are located here
  • example – examples (html pages, etc.) are placed here.  This folder can also be used for hosting an app if desired

Tips ‘n Tricks

Automatic Provisioning (typings)

In Visual Studio Code, press ctrl+shift+B (or ‘npm run build’ from a command line).  This will build the example code so you can ensure everything works.  The first time the build task runs, it executes the provision.js script which installs TypeScript typings and then removes itself from the build script of the package.json file so typings aren’t reinstalled every time you build.

Webpack loaders

I’ve included an html loader (commonly used for requiring templates in various front-end frameworks like vue.js)

TL;DR

wet-template is a minimalist project template for WebPack and Typescript — clone it, npm install it and go.

 

 

 

 

Troubleshooting Aurelia (A.K.A. Where are my Custom Elements?)

Aurelia is a great JavaScript framework for creating Single Page Apps (SPAs).  It’s especially easy to learn for engineers that are familiar with WPF and the MVVM pattern-the documentation even uses the familiar terminology of views and view-models.

While it’s still in beta (as of today – Mar. 24, 2016), there is a decent amount of support available on Gitter, Stack Overflow and some documentation available on Aurelia.io.

Recently, I’ve been using Aurelia in conjunction with Cesium to develop a 3-D visualization app.  I’m using Aurelia for navigation, custom components for various forms of selection and the main navigational view component contains Cesium:

.HypersonicScreenshot

One simple, but potentially frustrating issue I’ve run into is when my custom elements don’t appear in the app.  This frequently leads me into the following train of thought:

  1. Why aren’t my custom elements showing up in Aurelia?
  2. Are there any warnings / errors in the browser console?
  3. Is there a bug in my View (HTML)?
  4. Why aren’t there any warnings / errors in the browser console?
  5. Is there a bug in my ViewModel (js)?
  6. Where are the darn warnings / errors in the browser console?
  7. Is Gulp watch working?
  8. What the heck is wrong with this thing — why aren’t there any warnings or errors!
  9. Why didn’t I become a Doctor like my mother always suggested!?!

After struggling with this train of thought for a while I finally realized I’d missed the following little snippet in my containing element’s HTML:

<require from="my-custom-component"></require>

As you may have guessed from the above rant, this does not generate any warnings or errors.  Instead, you may just end up with an empty component like this:

<my-custom-component></my-custom-component>

So, next time you start asking yourself “Why aren’t my custom elements showing up in Aurelia?” make sure you haven’t forgotten a <require> tag in the containing element.  Either that or choose a less frustrating, time-consuming career and go back to medical school.