Thoughts on a Portfolio

I was screening a candidate today, an international phone call and a review of some of his code on github.com, he made a solid showing. For myself I've never presented my code as a portfolio although I've often said that I think a good professional should. That got me to thinking about what I would like to have in a public repository of my work, how I would like to be judged. What do I want my portfolio to say about me?

• I should want to work for a company that writes code like my portfolio.
• It should be the sort of code I would like to be paid to write.

It's about looking professional, and it's code, so I'd aim to get people actually playing with my work. There's no better advert for a programmer than the quality of their working programs.

A few things come to mind regarding the presentation in the repository:

• It should look real, like you were genuinely using it or it's been made for someone.
• Any reasonably experienced person should be able to click through and figure out what it's about without any wrong steps.
• The tests should be an obvious and effective first place to look, (I'm always impressed when I can figure out the motivation and typical use of open source by scanning through some tests).
• If you're one of many contributors then your contribution needs to be substantial and easy to find.
• It should be relatively easy to deploy and run for anyone who takes a look at it, ideally both a launch script and instructions.
• If it's a web application then consider hosting it somewhere, if it's a stand alone application make it downloadable and installable (and removable).
• Don't present non-functioning work in progress in your portfolio (maybe you need a separate repository for that).
• Don't present old school work unless you are a recent graduate.

And in terms of the code, (some of these points are my responses to code I've read while reviewing various portfolios):

• It should be clever without being obscure.
• It should in general follow the common idioms of the languages, be obvious and relatively future proof.
• The code should speak for itself, comments that just repeat function names or similarly obvious information are redundant; good file, module, class, function and variable names are better.
• Comments should explain what isn't obvious in code, like larger scale motivations or algorithms, or expected patterns of use. Although tests should also carry that information.
• As a portfolio it shouldn't just repeat the same thing, so variety in languages:
  • Something in the Java/C++/C# vein,
  • Something in the Python/Ruby vein,
  • Perhaps something in the emerging languages vein like Scala/Closjure/F#
  • Perhaps a restricted environment tool like JavaFX/Flex/JavaScript.
• At least two different types of applications:
• A retained state stand alone application,
• Plus a web app,
• Perhaps a smart phone trinket,
• A library or some utility scripts could also be worthwhile.

It's a portfolio, put your best foot forward.