Looking for code snippets in all my source places

June 8, 2015 12:02 PM

How do I compile a compelling code portfolio? What kind of selection criteria do I use, or can you recommend resources for developing it?

I'm an electrical engineer who specialized in DSP and currently does software development and system engineering work. I hadn't been planning on job hunting, but an opportunity came up that sounds pretty cool. I'm a strong candidate, and the posting notes that they will require a code portfolio.

I have never put together a code portfolio and my generally excellent google-fu isn't finding a solid guide to selecting code examples. If specifics matter, the position is looking for experience with Python, R, JavaScript, Java, C, C++, Clojure, PostgreSQL, MongoDB, and Git. I'm missing Clojure and MongoDB, but I have all the others and more.

The guidance I've received so far is that code doesn't need to be runnable and I should get more info about generally what they're looking for, but I'm not sure what kinds of work are important to showcase so someone reading it will know that I know what I'm doing.

One wrinkle is that I work for the DoD, so some of my work is not available. I use GitHub for private repositories for my personal work.

Any tips or guides on how to choose code for a portfolio, or links to references about the matter?

posted by bookdragoness to Work & Money (5 answers total)

Best answer: As an engineer who has to read the code portfolios that prospective new hires turn in, let me tell you my Entirely Correct opinions:

1. I don't want to see boilerplate -- If you hand me a Ruby on Rails app, my first task is going to be finding the actual, useful code that you wrote yourself. Don't make me do that. Do you have a model or controller that does something cool or demonstrates your familiarity with a topic? Just give me that. Leave out the cruft.

2. I'm (probably) not going to run your code -- unless it's something simple and useful, the odds that I'm going to attempt to execute your code are basically nil. Because I have better things to do, because running that code securely is an added time-sink, because the additional information gained is pretty low. If you want me to see something you wrote working, either make running it dead simple (as in, no more than three commands, all of which I should be able to copy and paste) or publish a working application somewhere that I can interact with as a user.

3. There'd better be a README or twelve -- I want prose about the portfolio in general. What will I be seeing? What are you good at? What don't you have examples of because [reasons]? Then I want to see an index of the actual samples themselves with a very short description of what I'd get from looking at them. "Rails controller for [app name]" tells me almost nothing. "Rails controller for [app name] where I came up with a creative caching solution to improve page load times" is far better.

Then, each individual code sample should have a README and that document should set the stage. What problem were you trying to solve? Why is this something worth showing off? What parts of the system did you not include but are critical to understanding the context? If you want to really impress me, here, also tell me what's WRONG with the code you're showing me. Are there bugs? What trade-offs did you make, and why? Prove to me that you understand the code you're showing off deeply.

4. Your code samples should have a purpose -- Every piece of code you include should be there for some reason other than that you wrote it. Make sure you know what it's trying to prove. You don't need six examples of your ability to write code in a given design pattern. Be able to summarize, to yourself, what you want the hiring manager to learn about you from a given code sample. If you can't, or if the code sample doesn't demonstrate that point, get rid of it. I'm not going to spend days (or, if we're being honest, even hours) reading your code sample. Have a point and get to it quickly. The worst thing possible is for you to submit a code sample and I miss the really outstanding code because I spent my time reading code no more elaborate than web programming tutorial.

5. The code should be "good" -- Whatever that means. Don't kill yourself to "fix" your code, but if you've got something that is egregiously sloppy but was still noteworthy, it's worth either fixing or explaining why it is so bad (was this 11th hour code at a hackathon? were you 7 years old? Did someone force you to use EMacs and this was the best you could do?).

At the end of the day, remember that this is a sales job. If it takes me more than 15 minutes to get a feel for your general level of competency, there's probably too much crap in your portfolio. If it takes more than 30, I'm probably just going to assume you're not very good . . . either at programming or at communicating about code, both of which are vital skills for developers and engineers.

A colleague of mine wrote on this topic here for a slightly different take. Feel free to MeMail if you want to chat privately.
posted by toomuchpete at 1:41 PM on June 8, 2015 [21 favorites]

If I could favorite toomuchpete's answer 10x more I would do so. +1.
posted by cgg at 2:32 PM on June 8, 2015 [3 favorites]

Best answer: That's a great answer. I will just say that I've done the interview process a few times on both sides, and unfortunately no one spends more than about 5 minutes looking at a code portfolio. Maybe impressive-sounding file names are best since that's all they'll likely look at :). A working online demo would be great since NO ONE is ever going to install and try out your stuff.
posted by miyabo at 2:38 PM on June 8, 2015 [2 favorites]

Response by poster: Thanks for the input!

Sounds like I was overthinking it, which is unsurprising. I really appreciate the detailed advice!
posted by bookdragoness at 7:53 PM on June 16, 2015

Response by poster: As a follow-up, from the advice above, here's how I determined what to put into the portfolio:

1. Selections to demonstrate multiple languages
2. Selections with an interesting problem or hook

I mostly selected from existing projects, and ended up writing a new project to demonstrate certain techniques or competencies.

The bulk of my effort preparing the portfolio went into writing extensive READMEs, which included:

1. File listing (referencing files in a zip of code)
2. Problem statement/overview
3. Brief overview of how I solved/developed and approaches with explanations and sometimes pictures or flow diagrams
4. Bulleted list of code references of relevant/interesting code, including file and line numbers
5. Bulleted list of "Key Features" of the program

Where applicable, I also included a "How to run" and/or "Future Improvements" section(s) talking about what I would do and why/how. I also included sample output for some portfolio components.
posted by bookdragoness at 12:17 PM on August 6, 2015 [2 favorites]