Posted on

Why (and How) I Write Code With Pencil and Paper

If the thought of handwriting code seems silly, it might surprise you to know that it’s inevitable. If you’re unsure, think about the last job interview you did, and remember how there was no computer around in the interview room — just your interviewers, a blank sheet of paper, and a blue ball-point pen.

For the students among you, it’s even a bigger deal as your grades hang in by the lines of code you had strategically squeezed into the available space in your answer sheet.

And not just that, experienced programmers can point you to the bundle of A4 sheets they had removed from the office copy machine to scribble down a particularly complex algorithm they had been working on.

So whether you’re an exam student, potential job interviewee, or someone wanting to resolve their programming dead ends, I hope this article helps you out when you put your pen to the paper to code.

Although I will focus on the analog aspect of writing code, you can apply these steps to coding in any form or language. So consider this to be also like a generic coding guideline that works specifically for me but can also be very useful to you in your work.

Why write it down?

Before we start, it’s essential to understand that no one expects you to jot down production-ready code in a notebook. It’s not like you can drop that into a code editor and compile it without an error. If producing perfect code was the goal, you would be seated in front of a computer in the interview rooms and exam halls.

The purpose of handwriting code is to work through logic in advance. There’s s desire to “get in the browser” as soon as possible in design, but there is conventional wisdom in sketching designs by hand. A low-fidelity medium encourages quick experimentation and inexpensive mistakes.

White lined paper with cursive handwritten notes on using :nth-child.
The toil of trying to figure out how to affect surrounding items with one click (from my last article)

The same can be true of code, mainly when working out syntax and semantics. That said, getting the correct syntax and semantics is always a plus point, though not the sole focus of the whole handwriting exercise.

Let’s see where we can start when it comes to handwriting code.

Know your question

During my final year in college, I couldn’t do an internship or even attend campus interviews because of health reasons. As a result, my very first job interview was quite literal with high stakes.

When I look back now, the interview was pretty easy. But having never attended one before, I was anxious beyond reason. The first thing the interviewers asked about programming was if I could output an inverted triangle made of asterisks. As I said, it was easy — nothing a for loop can’t handle, right? But like I said, my anxiety was through the roof as well.

I took a deep breath, pressed my palm against the blank sheet of paper they had laid out for me, slid it as slow as possible towards me on the table (buying time, of course), clicked the pen, and then I did something right.

I first drew an inverted triangle made of asterisks. That’s how I found my feet on the ground to start answering their question.

I’ve seen otherwise brilliant developers get something wrong simply because they never fully grasp what it is they are solving.

The questions we work with are not like the questions physicists or mathematicians solve. They get a set of parameters and find the missing ones; our questions are also our results. We are already told what our results are — we have to figure out how to reach them. That’s why it’s imperative to know the question well because you’ll see the result.

Writing down or drawing out what you want to output is one of the best ways to start your coding. I understand that in our fast-paced industry, the expectation is that we have to jump right into the programming by running a “hello world” demo. And that’s great to familiarize yourself with an unfamiliar syntax and shake off your anxiousness about trying something new.

But when someone asks you a question and gives you a result to work up to, wouldn’t it just be better to put that down first? That question/result is not only your starting point but also your point of reference. At any step in your coding, you can look at it to ensure you’re working towards it and that you’re on the right track.

So whether in your answer sheets or in that blank A4 paper you’re about to write in, start by taking a second and writing down what it is you’re trying to output. You can put it in the margins or a corner if you don’t want it to be a part of your answer. Just make sure it’s somewhere where you can keep referencing it.

Outline your code

This step is like a double-edged sword. It can get you a roadmap to your program or waste your time. My job is to make sure it’s the former.

So, first and foremost, I like to say: outlining code is unnecessary if the scope of your problem or question is small. Again, this practice is neither prescriptive nor universal to all projects or situations. Imagine I’m your interviewer, and I ask you to write how to center an element in a web page using CSS in as many ways as possible. You won’t exactly be needing an outline for this. The code snippets are relatively small for each method.

But now, let’s say I assign you to write a web application that captures user signatures via a touchscreen interface and then saves the signature on the server. Not so straightforward, right? You’ve more than one thing to figure out. Perhaps, a little outline can help.

  1. UI for capturing signature — HTML Canvas? WebGL?
  2. Disable pointer events on the rest of the web page when the user is signing
  3. Convert and save the captured image to a PNG file — JS
  4. Then convert it to blob (maybe) and save it to the visitor’s log data table.

I’ve written a rough sequence of actions I think I might have to code. It could’ve been shorter or longer, depending on what I wanted from it.

I highly recommend outlining code for client projects. Write the outline along with your user requirements or on the back of wireframes you’ve printed out.

Your quick snapshot of bullet points gives you a map, a to-do list, and a checklist to verify against when you reach the end of the project — pretty much your whole project’s summary in a low-fidelity list. It can also become a template to start your next similar project.

But like I said before, this step is like a double-edged sword. You’ll have to keep this short for examinees and interviewees when there are time constraints.

If you don’t know where to start, write down just three essential functions you’ll have to code in your application, and if you have got the time, make it five.

But that’s about it. Spend as little time as possible on this, and don’t sweat over the details. The outline is not going to score you extra points. It’s there only to help you make sure you have everything covered. It captures your initial gut reaction and keeps you honest throughout the project’s life.

Longhand vs. shorthand

White lined paper with cursive handwritten notes in black ink.
A quick reference to disable text selection

Time to start coding. So, what do you write? “Bdrs” or “border-radius“; “div -> p” or “<div><p></div></p>“; “pl()” or “println()“; “q()” or “querySelector()“?

If someone else is grading your code, then there’s no choice. Leave out abbreviations, pseudo-codes, Emmet shortcuts, and any other form of shorthand writing. Otherwise, there’s no reason to assume that anyone reading this knows what your abbreviations mean.

It’s really up to you.

If you’ve gotten out of touch with writing by hand — and many of us have — it’s better not to go overboard with the longhand notations, as they get tedious. At the same time, there’s no such thing as being too frugal with your writing. Not if you want to be able to look back on it one day and understand what you’d written down.

I have an open file in my note-taking app and a lined notepad on my desk where I write down code snippets I want to save for later reference. They are unorganized, just a long stream of snippets. That’s why when I browse through older notes, I wouldn’t know what I meant to write if I had not written them down clearly.

I forget syntaxes all the time. For instance, I’ve been using the arrow notation for JavaScript functions since it was introduced (because it’s shorter), and I’m pretty sure if someone suddenly asks me to define a function using the function keyword, I might even misplace the parentheses or the function name, inciting a syntax error.

It’s not unusual for us to forget syntaxes we haven’t used in a while. That’s why it’s better to write your notes clearly when you know you need them for future reference.

The non-sequential flow of code

Unlike the last step, which doesn’t apply to those of you interviewees and test-takers, this one is catered especially to you.

Most programming languages are interpreted, compiled, and executed so that sometimes pre-written code in the source is executed later when called. We do it in JavaScript, for example, with function calling — functions can be defined initially, then executed later. Examinees and interviewees can use this to start working on the critical point of your answer first.

As I’ve said from the very beginning, the purpose of handwriting code is to work through or test the logic of whatever it is you program. It’s best when you focus on resolving that first.

Let’s take a classic textbook example — a program to find the nth Fibonacci number. If I were to write a simple outline for it, it would be something like this:

  1. Get the input.
  2. Calculate the Fibonacci number.
  3. Summarise the output.
  4. Print the output.

All the steps in that outline are essential; however, 1, 3, and 4 are more obligatory. They are necessary but not important enough to focus on right away.

It’s better to start writing down the code to calculate the Fibonacci number rather than to fetch the input. Wrap it in a function, then go ahead and write the code sequentially and write down a line to call that function where appropriate.

Spend your time writing code that focuses on the heart of the problem.

Real professionals can skip ahead. Let’s say I have a client project, and I have to work with some triangle geometry — got two sides, opposite angle, and gotta find the third side’s length. And I’ve decided to scribble on paper to get started rather than opening my IDE.

First, I would draw the triangle, of course (that’s something I’m very experienced with, as you can tell). I would write down some sample lengths and angles. Then I’d write the formula (compliments of online searching, for sure), and then I’d jump right to the code for the function.

There’s no point in me writing down the obligatory steps even though I’ll need them in production-ready code. But it would be different if I had to write that on an answer sheet in an exam. I can’t skip the other steps; however, I can still start with the code for the formula.

Pseudo-code

Chris has already written a handy article on pseudo-code that I highly recommend you give a solid read.

For all those professionals who feel like the whole handwriting code thing doesn’t seem like your cup of tea but still might be curious if it can help you, then pseudo-code might be the balance you’re looking for.

It’s similar to outlining the code, as I mentioned in one of the previous steps. However, it’s briefer and feels more like shorthand coding. It’s sometimes also referred to as “skeleton code.”

Here’s some quick pseudo-code for a CSS grid layout:

Grid
5 60px rows
6 100px columns

There isn’t much to write! So, even though putting a pencil to paper is excellent for this sort of thing, it’s just as effective, fast, and inexpensive to jot some pseudo code into whatever program you’re using.

Space and comments

I believe code is 90% keywords and 10% tabs. Withoutspacesthereadabilityofwordsdecreases. Indentations are necessary for handwritten code as well. However, please don’t use it for every level because the width of the paper will limit you. Use spaces judiciously, but use them.

Yellow unlined paper with code handwritten in cursive in black ink.
Prized OG snippet, written with extra TLC

If you’re writing code for your use, I also believe that if you’ve followed everything I’ve mentioned so far and have already written down your output and an outline on the page, you may not even need to include comments. Comments tell you quickly what its following set of code does. If you have already written and read an outline for the code, then comments are redundant notes.

However, if your judgment says to put down one, then do it. Add it to the right side of the code (since you won’t be able to insert it between already written lines the way you could in, say, VS Code). Use forward slashes, brackets, or arrows to denote that they are comments.

For examinees who are unconfident with a certain syntax, write down comments. This way, at least, you’re letting the person grading your paper know your intention with that incorrectly formatted code. And use only the correct delimiters to denote comments — for example, that would be the forward slashes for JavaScript.

Analog vs. digital

As I mentioned earlier, everything I’m providing here can is generic coding advice. If you don’t want to try this with physical paper, any note-taking application also works.

But if you’re going to try the digital route, my recommendation is to try using something other than a straight note-taking app. Work with more visual digital tools — flow diagrams, mind maps, wireframes, etc. They can help you visualize your result, the outlines, and the code itself.

I am not much of a digital citizen (except for working on the web and recently converting to reading e-books), so I stick to physical notebooks.

My favorite tools for handwriting code

Any pencil and paper will do! But there are lots of options out there, and these are a few choice tools I use:

There is no “write” way to code

I hope, if nothing else, my little way of handwriting code with pencil and paper makes you evaluate the way you already plan and write code. I like knowing how other developers approach their work, and this is my way of giving you a peek into the way I do things.

Again, nothing here is scientific or an exact art. But if you want to give handwritten code planning a try, here’s everything we’ve covered in a nice ordered list:

  1. Start by writing down (with sample data, if needed) the output of your code.
  2. Write an outline for the code. Please keep it to three steps for small projects or ones that are less complex.
  3. Use longhand notations. Developers writing for themselves can use shorthand notations as long as the writing is legible and makes sense to you when you refer to it later.
  4. When under a time constraint, consider writing the code that tackles the heart of the problem first. Later, write down a call to that code at the right place in your sequential code.
  5. If you feel confident, try writing pseudo code addressing the main idea.
  6. Use proper indentations and spaces — and be mindful of the paper’s width.

That’s it! When you’re ready to try writing code by hand, I hope this article makes it easy for you to start. And if you’re sitting down for an exam or an interview, I hope this helps you focus on getting the questions right.

Why (and How) I Write Code With Pencil and Paper originally published on CSS-Tricks, which is part of the DigitalOcean family. You should get the newsletter.

Posted on

The Importance of Career Laddering

The title of this article is misleading. It’s not actually very important for an Engineering Manager to use career laddering, per se, or my process. It is, however, very important that an Engineering Manager is clear with their employees about what their expectations and direction, not to mention where they are in terms of a raise and promotion.

I’ve personally found that career laddering can help with this, but is only one small supportive piece of a whole. You can have formalized career laddering in place and still mislead your staff, so it’s critical that career laddering docs are just one tool embedded in a deeper process.

What is a career ladder?

Before we dive any further, let’s clarify first what we mean by a career ladder. Career laddering is typically a system used to show what expectations are at different levels of a role, a purpose of which is defining how one might be promoted. This can have different forms, but tends to be an internal document that states the expectations of a staff member at any given stage of their career.

Here is a microsite I set up where I open sourced all of my career ladders >

As you can see in the site, it outlines each of the different levels of the job, as well as the roles and responsibilities expected at that level. In this particular example, there is a basic concept that ties the whole thing together:

  • To get to Senior, you’re the best “you” you can be — you perform your role exceedingly well and you’ve reached a high potential for your own output.
  • To get to Staff, your focus is really to expand beyond yourself. You start teaching people the great things you learned and help serve their needs.
  • To get to Principal, you’re creating systems that scale beyond yourself. You’re no longer helping folks be like you — you’re helping them where they are. A lot of your activities are enabling the success of everyone around you.

What I like about this system is that the job of the most advanced folks becomes helping support and grow other people or system in such a way that benefits everyone. Principal-level folks don’t lord knowledge over others; they work to put the knowledge into practice in a way that’s truly helpful.

Again, it’s not important that you use my exact system, but I want to show that having clarity about the roles and expectations of each team member can really go a long way. Why? Let’s dive in.

Photo by Damian Zaleski on Unsplash

Clarity

“You can’t call yourself a leader by coming into a situation that is by nature uncertain, ambiguous — and create confusion. You have to create clarity where none exists.”

— Satya Nadella

I have never seen employees more demoralized than when they’re unsure where their career is headed and whether their title/compensation is fair. It’s frustrating, exhausting, and can lead to burnout. It’s also incredibly distracting — who can get their job done when they have no clue if what they’re doing is valued?

Some may ask about intrinsic motivation. You can have an employee that cares intrinsically about their work and still feels misaligned with the overall impact that the company sees in it. That’s often when the disconnect feels the most hurtful. If you have an employee who is working extremely hard and doing absolutely everything they can, the feeling of being undervalued can be heartbreaking.

Clarity with people about their level and being explicit about what they should be working on is critical. Transparency around timing for such a promotion cycle if you know it can help as well.

There’s a bit about trust in here, too. If you are working with someone on their growth path and trust that you will honor it, you enter into a sort of partnership.

Personally, I love it when the qualities you’re working on are things that would serve them anywhere, not just the company. These should be things that expand their skill set. These types of tasks typically take some long term work, but it can be very rewarding to work together on because there’s a larger purpose.

One thing is critical: if you guide employees on this journey, you need to give them the promotion at the end. The promotion is a change in title and compensation, of course, you break the bond of that partnership if you don’t follow through. Always give the promotion if that person has earned it on their end.

Putting career laddering to work

I mentioned that a career laddering document alone will not help drive a team, and I also mentioned the importance of clarity. So, let’s tie this all together and talk through how to use this in practice.

Photo by FLY:D on Unsplash

Step one: The big picture

I am one of those annoying managers who asks people where they’d like to be in five years. I call it “annoying” because it’s a lot to think about. But I still ask it, not because I’m not looking for a perfect answer, but because it gives them an opportunity to consider their future and, usually, they tell me something I should know.

Here are some examples:

  • I don’t really know what I want to be doing but I know that I don’t want to still be focused on build systems in five years.
  • I’m not really sure because I think I might want to be a manager, even though I haven’t tried it yet.
  • I want to be able to go camping whenever I feel like it, take my family with me, and work on the road.
  • I want to be sure that fellow developers in Africa have every opportunity they want.

Notice that these are not a formal outline for the next five years. But you can already get a sense of people’s values, their boundaries, and what we may want to incorporate as part of their working environment.

Step two: Career laddering review

If you don’t know where you are going, you might wind up someplace else. 

— Yogi Berra

In this step, we go through the career laddering doc. What I typically do is have an employee read out every list item in their current role to me, then self-assess the progress they’ve made on each item. I sound off a bit on it. We generally align; people tend to be fair and honest. I personally think it’s important that they read their list to me instead of the other way around, there’s a sense of ownership that way.

We also go over the next stage in their career and the list items for it. At the end of the process, we break down any common themes. For example:

“You’re solidly a Senior, and doing quite well in your role. To get to Staff, you need to be helping others a bit more. Let’s make sure you have the time to be available for more PR reviews and pairing in the next few weeks. Let’s also talk about getting that internal tool you were building over the line, that would likely help the team move faster“

Step three: 30/60/90

The next step I do is called a 30/60/90. The concept is that you break down the work you want to be doing in 30, 60, and 90 days. 

I tend to do this with a bit of a twist: We start with 90 days and ask: what would you like to accomplish here within the next three months? Since the career laddering is fresh in their minds, there’s already some guidance on what their focus should include. It’s safe at this point to let them drive, and tell you what they should be doing instead of the other way around. 

Sometimes this can be quantifiable: 

  • Engineering: I would like to close five issues each week, ideally with at least two PRs.
  • Docs: I would like to address content gaps on two features.
  • Anyone: I would like to pair with at least two people.

It can be expressed as a metric:

  • I would like to help increase adoption of our npm package by 10%.

Or it can be less measurable:

  • I would like to try to understand our component library a little more as a newcomer.
  • I would like to try to interrupt other people less in meetings.

All of these are valid.

Photo by Christin Hume on Unsplash

Now that we’ve taken the time to define the 90 day plan, we figure out what’s doable in a 30-day period. Again, it’s up to them what they think they can accomplish in this time. I only chime in if I think they’re being too ambitious, or they are missing something that the company needs.

It can also be helpful to state that things change, and nothing in this plan is set in stone — other things may come up that need attention. We’ll adjust, it’s no big deal. I honestly don’t find the 60-day piece to be very useful because a lot changes in a month. I usually skip it, but you can absolutely use it if you find it helpful!

We also get to talk through what they shouldn’t be doing. If you find that something they are spending time on is not useful for the employee or the company, you may be able to remove the task and clarify this to other stakeholders. The employees themselves may not be able to have that conversation.

This can be incredibly useful for someone who may be an over-performer, but are burning out. It helps us align on the tasks that are overextending them so that they can properly prioritize and focus. It’s tempting to think that over-performers need less guidance but I’ve found that they tend to need more clarity, not less, so that we can define scope and help them set a good direction.

I’ve also seen under-performers turn around after the career laddering process. What one might see as a lazy quality in that person might actually be a symptom of being misaligned with the purpose of the tasks. A career ladder helps them recognize what, when, why and how the things they’re working on fit into the bigger picture.

Iteration and reflection

From here, it’s probably pretty clear what you do — keep revisiting the list! I try to set a reminder in our one-on-one doc to revisit the 30/90 plan in about a month. When we check in, we see how far they’ve come on each task, putting little checkmarks next to what’s done. I’ll sometimes put a celebration emoji on something they did particularly well — I believe it’s important to celebrate those as successes, even if it makes me sound like Mr. Rogers. Show folks that you appreciate their work and how far they’ve come.

From there, you can carve out another block for the 90, so they have direction for the next 30 days. If they didn’t finish something, carry it over to the next month.

Every few months, we’ll go back and do the career laddering exercise again, but this time denoting the progress that’s been made in every area. When they’ve filled their end of the deal of the things you asked them to work on, it’s time to promote them! 🎉 Don’t forget to celebrate that as well!

Wrapping up

This is not the only way to provide direction and clarity in a person’s work — the sky’s the limit. Anything that provides clarity for your staff can be helpful.

What I’ve liked about the career laddering process is that there are no surprises: people know where they are, and what it will take to get to the next level. There are no surprises in 360 reviews as far as what stage they’re at and what they should be working on between now and the next check in. The progress is a tangible thing that becomes a partnership between the both of you, and the work is just a unit within something measurable on that path.

It can be clarifying for everyone around: they know the system — there should be no surprises why a person is getting promoted at a given time. Hopefully that alleviates any tension in the process. 

Our collective aim as managers should be taking the careers of our employees as seriously as we do the team’s technical processes. Promotions ideally come exactly when and how everyone thinks it will. The goal is to set your team up for success: everyone has a good path forward and they can focus on doing work that is both impactful and rewarding.

The post The Importance of Career Laddering appeared first on CSS-Tricks.

You can support CSS-Tricks by being an MVP Supporter.

Posted on

Where I Think “Agile” is Headed — Part Four: What Does “Agile” Mean?

I started this series asking where “Agile” was headed. (I didn't like what I saw at the Agile 2019 conference.) Part One was about the 4 big problems I see. Part Two was why we need managers. Part Three was about how people want a recipe. This part is about what “Agile” or “agile” means.

I understand that people want what they perceive as the value “Agile” will bring them. Let's return to the Manifesto for Agile Software Development, what I call the “Agile Manifesto.”

Posted on

How to Use Data to Improve Your Sprint Retrospectives

Most agile teams do sprint retrospectives at least once a month, to iterate and improve on their software development process and workflow. However, a lot of those same teams rely only on their feelings to “know” if they have actually improved. But you need an unbiased reference system if you want to compare how two sprints went.

Depending on what you’re focusing on, there are metrics that you might be interested in. For instance, if your team uses estimation, tracking how those estimates pan out could be worthy indeed, and comparing the variance across sprints could provide such a metric.

Posted on

How to Get Your Engineering Team Involved in Product Efforts

At Anaxi, we don’t have a product manager. Seem weird? We’re not the only ones to do that. For instance, that’s also the case at Apple. But in our case, this role is spread out across our remote engineering team. In this article, I will detail why we do this and how we do it. To be honest, there are many things we’re still iterating on, and refining our processes will just be a constant effort, as it should be in every company. Note that our process works for any engineering team, working together in the same office or remotely.

Why You Want Your Dev Team Involved in Your Product Definition Efforts

In our particular case, our target customers are developers and engineering managers (and later on, product managers). So our engineering team also happens to represent our own customers. It stands to reason that they should have deep insights on what has value and what has less, probably more than a non-technical product manager who thinks they can understand the audience.