Forem: CodeSee

Tales of regret from developer onboarding

Matthew Revell — Tue, 01 Feb 2022 14:01:00 +0000

Whether you're just starting out as a developer or you've got years under your belt, learning a new codebase is a defining experience.

Onboarding shapes not only your enjoyment of that project but can influence what sort of work you go on to do next. Either you're running screaming in the opposite direction, or you've found something you want to do again.

For every codebase onboarding that feels like an effortless walk in a sunny meadow, there are plenty more that evoke a 3am hike up an unlit rocky path during a hurricane.

Below is an inexhaustive collection of postcard-sized onboarding stories from real developers. They illustrate some of the specific ways in which onboarding can go wrong, and, at the end, there's a hint at one way we might make it better for the developers who come after us. Names have been changed.

I've suffered, so shall you

If a problem shared really is a problem halved, then perhaps that explains what happened to Mark.

The first day on the job, the incumbent developer asked a question, "How do you feel about spaghetti code?" Not leaving any time to answer, he followed up with, "Because what we have here is code soup."

The product should have been straightforward. It was a web front end to research data held in a PostgreSQL database. However, Mark was the fourth developer to work on the system in a short period of time. It was almost as though each prior developer had gone out of their way to avoid any consistency with their predecessor. Instead, they picked the tools and conventions they preferred. That led to fun situations such as Hibernate taking care of user and project records, while JDBC was used for general querying. As Mark says, "Why have one data abstraction layer when you can have two?"

Sure, the codebase itself was a mess, but the onboarding was essentially a surrender. "I know this is terrible, but I've suffered, so that means you should too," probably isn't the ideal onboarding maxim.

Mismatched expectations

Starting a new job is somewhat stressful, even in ideal circumstances. There's the pressure to show your best in those 30-60-90 reviews and to win round your new colleagues.

But for Gavin, a Python developer, starting one job, in particular, was especially fraught. "They knew I wasn't a Ruby developer but somehow also expected that I did know Ruby."

On top of learning the new codebase, Gavin also had to learn a new language. Not an impossible task but also one that no one at the company had made allowances for. "They pointed me at rubykoans.com and wished me well. The Koans are good, but they don't cover de facto essential stuff like Rails," Gavin said. After years in the Python ecosystem, he also found that the difference in approach between Python and Ruby docs took some getting used to.

For Gavin, it was the shock of the mismatched expectations, combined with his own desire to show his best work, that made this particular onboarding hard. "One person's experience of learning new tech can be worlds apart from your own: I was joining a company of Ruby enthusiasts who probably found it hard to put themselves into my shoes. I had 20 other things competing for my time and attention, as well as that huge pressure to be productive. Having to also learn Ruby, Rails, and the special way in which Rails was used at that company, before being able to be productive was very stressful. I came close to quitting or being fired."

Why can't you just understand?!

There are situations where a problem space is just plain hard. Some things take time to understand fully. But other times, it's not the problem that's hard to understand, it's more that the person getting you up to speed lacks the necessary empathy.

One developer, Gráinne, found that the person onboarding her was perhaps too close to the code to see it from a newcomer's point of view.

"On my first day, I showed up, got access to the code, and then had a two-hour sit down with the CTO. He was also the architect of the product and the lead developer. The trouble was that he talked very fast and got quite exasperated when you didn't immediately understand what he was saying."

For Gráinne that meant making whatever notes she could during the onboarding/interrogation and then trying to fill in the gaps by reading the code.

But even past the onboarding itself, a Monday morning could put things back to square one, "The CTO would often, over a weekend, massively change huge chunks of the code, breaking things in horrible ways, and then would shout about it until we fixed the mess."

We are unreliable narrators

Perhaps there's a theme that unites all of these stories: bad developer onboarding happens when there's no process or a process that fails to take account of people's different expectations and approaches.

Jeroen, a developer for a large multinational, put it this way, "Much of what we do in our business is communication. When we communicate, we're always referring to knowledge in our heads that we hope or assume is also present in the other party's head."

The problem is that it's hard for us to understand where that shared frame of reference ends and where we need to teach something completely new. Gráinne's CTO became frustrated when other people didn't understand his explanations because he couldn't imagine that other people had different experiences to his own.

Yes, we can grow as teachers and communicators. But there's a deeper issue. Onboarding shouldn't be an oral tradition.

Codebase onboarding as oral tradition

Let's take a moment to imagine something different.

You're sat around a fire with your family and close friends. The day has gone well. There is food, you have shelter, and yet there's a threat.

Some of the younger children have been wandering into the woods and eating mushrooms. Most have been fine, but one or two have become seriously ill.

You want to protect the children, but they don't understand why some mushrooms are bad, and others are just really tasty. You don't even know yourself. So, you tell a story to put it in a context you can all understand. You think on your feet. One of the elder members of your village can tell good mushrooms from bad. So, you say that all mushrooms have an evil spirit that only old people can cast out.

The story works. Over the years, it gets retold and embellished. Eventually, there's so much mythos around mushrooms that the original intent of the stories becomes forgotten. Even so, somehow, it continues to protect people, despite there now being a lot of unnecessary ritual associated with preparing mushroom-based meals.

Stories passed by word of mouth work act as vehicles for important knowledge. And we still use stories in our work as software developers.

Onboarding is a documentation problem

When everything is urgent, it's hard to prioritize work that will help you in the future. So it's somewhat understandable why onboarding a new colleague can be haphazard, clumsy, and inconsistent.

However, a bad onboarding is often actually a symptom of other problems. One particular issue is simply that many codebases lack good documentation. While individuals methods might have excellent comments, perhaps understanding of the whole system is less well documented. For example, there are teams where no two members would draw the same architecture diagram despite working on the same product.

At CodeSee, they've built tools that make it easier for teams to onboard new developers. And that's not by doing special extra work that just gets used in onboarding. It's by creating a shared understanding that benefits everyone who works on a codebase from onboarding and for the long term.

Regretful man photo by Nipan Chawcharernpon
Spaghetti by Maurijn Pach
Pomegranate seeds by by Tima Miroshnichenko
Angry cat by Pixabay
Scrabble tiles by Kathy Jones
Campfire by Jens Mahnke

Improve Your Developer Onboarding Path With the 10-3-10 Test

Matthew Revell — Tue, 18 Jan 2022 12:19:07 +0000

Getting to the point is essential for a smooth developer onboarding. Within seconds, you need to answer your product or project's what, why, and how.

But it can be hard to put ourselves in the shoes of a developer who knows nothing of what we do. That's why it's essential that we test and improve the onboarding path we give developers.

One way to do that is the 10-3-10 test. It's quick to perform, requires no special tools, and pretty much anyone can do it. Here's how.

From zero to Hello World in ten minutes

The idea behind the 10-3-10 test is pretty simple. A developer should land on your site without any context and achieve the Hello World state within 10 minutes.

Before a developer can get to that point, they need to know what the product does and then register to get a developer account.

Within all three of those milestones -- understanding, registration, and first product use -- lurks danger. At each stage, you're asking the developer to give you something on trust. At first, it's their time, then a small amount of information about themselves, and finally, it's both their time and their mental energy. It might sound over the top, but you need to reward the developer for each of those. Get the reward wrong, and the danger becomes apparent: the developer will lose trust and look elsewhere.

Drop-off is real

Work by Microsoft Research shows that typical web users decide whether to stay or go within 10 seconds of arriving at a web page. There is even an old study that suggests web page visitors form an opinion within 50 milliseconds of landing.

Keeping someone on the page long enough to explain the offering is just the start, though. Research on conversion rates by product analytics firm Heap suggests that 63% of SaaS users fail to complete product sign-up.

We are operating in a world of spam, clickbait, unregulated advertising, and other underhanded attempts to grab our attention. People have trained themselves to apply harsh relevance criteria to the information they find on the web.

Arguably, developers are not typical web users. Whether that makes them more or less patient will depend on their level of motivation, among other factors. What is clear, though, is that you have very little time in which to capture a developer's attention and then turn that into an interest in your product.

Three questions

There are multiple pressures on your developer onboarding flow. Product marketing might have a particular wording they want you to use. Someone in the growth team wants to try an experiment they read about recently. The VP of Sales is pushing for more data collection to assign new developer sign-ups to the appropriate salesperson.

Whether good or bad, the reality of these demands is that they can lead to a loss of focus. And in most companies, the demand for such change never really stops.

The 10-3-10 test is simple, repeatable, and quick, helping you measure whether you're continuing to serve developers. It asks three questions:

10 (understanding): Can a developer get a solid idea of what your product does within ten seconds of arriving on a developer-targeted landing page?
3 (registration): Can that person register for a developer account within three minutes of landing?
10 (first use): Can they get to Hello World ten minutes after first landing on the site? Whether you perform each test informally yourself or set up an ethnographic research session, it's worth diving into some of the factors that influence each stage first.

Understanding

How often have you been to a product website and come away none the wiser about what it does?

Competing demands too often lead to product pages that say a lot but communicate nothing. A common scenario is messaging that attempts to address too many different audiences at once. If a vendor compromises its message to serve both developers and, say, procurement managers, it'll serve neither well.

Sometimes, it's just that companies overthink how they talk about their products. As someone writing about a product, it can be hard to extract yourself from the context you have. It's tempting to build every comment, every meeting about the Chief Marketing Officer's vocab preferences, every barb thrown by the competition into that one very clever headline. But does that serve someone who just wants to know what problem your product solves and how?

The first step to passing the understanding test is to make sure you have a dedicated space to speak primarily to developers.

Next, stay specific and tell developers what your product does for them. Consider CodeSee's own home page. The headline and sub-head get straight to the action:

Visualize codebases faster

Map an entire codebase in just a few clicks.

The short follow-up paragraph then expands on that in a way that sticks entirely to the facts of how the product benefits developers.

Avoid the temptation to over-egg how you describe your offering. "SMS API," rather than "customer engagement solution." That kind of messaging has its place for certain audiences, and it makes product marketers feel good, but for developers, it's just another hurdle in the way of understanding whether that thing solves a problem that they have.

To pass the first test, a typical developer should understand the practical purpose of your product within ten seconds of landing on your developer home page.

Registration

Registration is a chasm in your developer onboarding. This is where developers must put the most trust in you by providing personal information without a clear idea of the pay-off. Provide them with guide ropes, way finding, and a hint of the reward that is to come.

First, how do you get a developer from the landing page to sign-up? The button or link you provide needs to be immediately obvious, not so wordy that people are tempted to skip it, and yet still communicate what's to come. Oh, and the copy must avoid scaring people off.

"Get started" and "Start now" are common choices. However, at least one study has shown that "Get started" attracts clicks, but not all are from people who are ready to try, download, or buy your product.

The Miro API's "Start building" is clearer. Click that, and you know you're about to get hands-on with the API.

CodeSee's "Try Maps now" communicates a lot in three words. "Try" tells you that you're going to be hands-on with the product while making it feel casual rather than intimidating. Naming the product enforces what's coming next, and "now" adds a sense that clicking will lead to a fast pay-off.

That's a lot for a button.

The registration process itself must stick to the principle of "minimum viable information". Sales and marketing colleagues might push to capture more and more information during registration, but your primary aim here is not to add another lead to the CRM. Instead, registration is about enabling access and then allowing the rest of the experience and product to win over the developer.

That doesn't mean you can't ask for more than just an email address and password. Most people have some tolerance for providing extra information. However, you should aim to frame at least some of those additional questions in terms of how they'll benefit the developer. Twilio's registration process is great for this. It asks some questions that might help their sales funnel but also collects information, such as your preferred programming language, that makes the developer dashboard more helpful.

To pass the second test, a typical developer should be able to get a developer account within three minutes of landing on your developer home page.

Hello World

Providing a smooth path through registration is good, but it's only a staging post. The developer's goal is to see for themselves whether your product solves their problem and whether they like the idea of working with your company.

There is enormous scope for ways to improve the path to Hello World, so let's focus on one thing. When the developer first logs into your dashboard, take them by the hand through the steps they need to achieve something worthwhile.

Such a first use experience is more than flashing up a quick-start guide or a click-through signposting of the dashboard's UI. It is a highly focused path that takes the developer from no knowledge of your product to that Hello World interaction. It builds on the supplemental information you've gathered during sign-up. Are they a Ruby developer? Great, get them to download your SDK's gem. They told you they work for a large company? Suggest they link their new account with Okta or other SSO providers to simplify integration with corporate sign-on.

That highly focused first use experience should contain everything the developer needs to get a feel for your solution and what it's like to develop with, in as efficient a way as possible.

If a typical developer can get to Hello World within ten minutes of the first landing on your developer pages, you've passed the 10-3-10 test.

And there's more

The 3-10-3 test is a blunt instrument, but it's useful as a way to keep us honest about whether our onboarding serves developers. It works well for commercial products, and there's plenty of scope to adapt it to onboarding a developer onto a team building a product or a developer joining an open source project.

Microscope picture by Public Domain Pictures

Hacktoberfest 2021: Celebrate Open Source With CodeSee

Nahrin Jalal — Fri, 01 Oct 2021 20:21:27 +0000

For the past 8 years, the days leading up to October have seen a flurry of activity in the open source community—2021 was no different.

It’s all in anticipation of the official start of Hacktoberfest—a month-long global celebration of open-source software. The event encourages giving back to the open source community by participating in donating effort, time, and funds to code-based events and projects.

At CodeSee, we’re passionate about this mission and committed to launching OSS Port just in time for Hacktoberfest 2021!

On OSS Port

With OSS Port, we aim to connect projects to people and ease codebase onboarding for all. Maintainers are invited to provide contribution best practices, support guidance, and interactive visual walkthroughs of their codebase using CodeSee Maps. Using Maps, contributors can readily onboard to a new project, with features to understand how files are connected, see how a pull request fits into the larger architecture, and more.

About Hacktoberfest

Last Hacktoberfest saw more than 66,000 challenge completions, with a total of 387,052 pull requests opened across 116,361 repositories. And this year’s event is expected to deliver even stronger results!

All of us on Team CodeSee are eager to support maintainers and contributors alike, share our knowledge, and connect with members across the community to do what we can to help lower the barrier of entry to open source!

OSS Port x Hacktoberfest Challenges

It all starts with the basic Hacktoberfest qualifications. Registered Hacktoberfest participants who are contributors must submit four quality pull requests to public GitHub or GitLab repositories in the month of October. Maintainers are also eligible to earn a reward for showing that they've completed 4 or more actions on unique pull requests.

To boost your impact (and swag haul), we invite you to take part in our OSS Port x Hacktoberfest Challenges. Head over to our landing page for complete details on how you can partake in the fun as a Maintainer, Contributor, or both!

Once you've completed our challenge(s), let us know by filling out this form. After the month of October is over, CodeSee will process and verify all submissions, then let you know how you can claim your limited edition OSS Port swag.

OSS Port x Hacktoberfest Challenge Rewards

We’ve got you!

Hacktoberfest expects hundreds of thousands of participants in 2021. To fully immerse yourself in the festivities, be sure to stay tuned for all that we have planned at CodeSee. October will be packed with weekly streams on our Twitch channel, helpful tutorials on the blog, and even a series of weekly challenges in Port for some supremely wicked swag!

At CodeSee, we believe every level of developer can confidently contribute to open source and help the community. If you have any questions or require support, reach out to us on Twitter or the OSS Port Discord Server.

From all of us at CodeSee, happy hacking!

How to Get Unstuck

Carmen Huidobro — Mon, 12 Jul 2021 13:05:13 +0000

This post is a part of CodeSee's Emerging Developer Track. Learn more and find out how you can participate here.

We've all been there. Coding away, solving a problem when all of a sudden we hit a blocking point. The thing we're trying to do doesn't work, or the problem seems completely out of reach. Heck, sometimes we might not even know how to begin solving the problem!

This might sound familiar, recent, even! After 10 years of working as a software builder, I still find myself getting stuck. I'll run into a bug that I can't reproduce reliably, I'll come up against an API that I can't seem to communicate with, trying to update a dependency will break others, or my CI builds just keep failing.

Let's take a look at a few tips to help you get unstuck!

Areas we'll be covering

If you'd like to jump ahead to a specific section, feel free!

Take a break, step away from the code!
Reframing the problem
Looking things up effectively
Leveraging debugging
Reaching out for help
- How long should I wait before asking for help?
- How to ask for help
- Pairing
Let's be clear, it's ok to get stuck

Take a break, step away from the code!

This tip has helped me many times in the past, so much so that I gave a talk on this very topic!

When I get stuck in a particularly sticky problem, I tend to get bogged down by it and try and hammer away at it, attempting to push through the frustration and/or exhaustion. It ends up in time not well used, or worse, my solutions might miss the mark.

So as the title implies, it helps to just, leave it for the time being! Depending on the time and looming deadline, this can vary in efficacy, but I find that if I go for a walk, or stop for the day, I can let my mind either work on the problem in the background or even coming back can bring in a fresher perspective that really jumpstarts a better solution!

Reframing the problem

Oftentimes when stuck on something, it might help to consider looking at the problem differently! Having a different perspective might even make us ask the question of whether the problem we're trying to solve is the right one. As written by Thomas Wedell-Wedellsborg:

Most people are fairly good at solving problems – but they are bad at diagnosing the right problems to solve.

Breaking the problem down into smaller problems

This approach to problem-solving is similar to that applied by Divide and Conquer Algorithms, where, as the name implies, we reframe the problem as a set of smaller problems, whose solutions are smaller by extension. What we can then do is approach each of these in isolation. This frees up our mind space to laser focus on those smaller problems and lets the larger solution build up!

One example of a tool to divide and conquer is git-bisect. Yep, built into your git tools!

git bisect is a command built into git with the purpose of helping us find out at which point we introduced a change to our codebase that we didn't want to add. By splitting all of the git history and checking whether the problem persists in each split, we drill down quickly to find out the commit that introduced it! This is also known as a Binary Search:

Looking things up effectively

No matter the skill level, it's super-valuable to look things up! Be it via online search engines or documentation.

There are brilliant technical guides out there for how to look stuff up on Google or DuckDuckGo, such as using quotation marks for terms that have to be included, or gradually making search phrases longer. Beyond that, some tips I've picked up over the years:

Look up that error message as-is: Loads of folks have likely run into the same problems. Even if they don't match 1:1, you'll likely unlock something!
Plug in that Stack Overflow solution: I recently learned that Stack Overflow's license allows reuse under Creative Commons Attribution-ShareALike, meaning you can reuse the code providing you add attribution. That said, in order to improve your understanding of a solution, it's encouraged to try and refactor that code, putting it into the best way that works with the style of your codebase. You'll often find that's required anyway!
Look up that aspect of a library in their Github repository: When something hasn't quite clicked in a library I'm using, it helps me to go into their repo online and see either what issues have been brought up on the topic, or even start trying to diagnose the issue in the library and potentially make a contribution!

The screenshot above shows lots of issues when I look up "compileDebugJavaWithJavac". I need to clean up my notifications, I know!

Leveraging debugging

Although we have tools to help us debug, this doesn't make all those tools debuggers.

One of my most-used tools is a print statement. It goes by many names in different programming languages, be it console.log, or puts, or printf, or System.out.println(). I've even gone and used alert in React Native projects!

And this is totally fine. If it helps you drill down to what's causing the problem, why not?

Various platforms will have debuggers on them too, like the web! Most browsers will have their own debuggers built-in, such as Firefox's Developer Tools or those from Google Chrome, both of which are extensively documented. But this isn't just limited to the web, we've also got specific debugging tools, like LLDB for all your macOS/iOS debugging needs, pry for Ruby, and so on!

Indeed, even editors like VSCode have their own debugging tools built-in for several languages!

Also hey, we're actually working on tools to help you with this! If you're keen on checking out our tools for understanding complex codebases in a streamlined fashion, consider signing up for our beta!

The most important part of debugging for me is to leave no stone unturned and try every theory I might have. You never know which piece of the puzzle is faulty!

Reaching out for help

Sometimes, with our heads buried in a problem, our perspective can get clouded. Having someone else step in with either more experience in the area or with their fresh perspective can be so handy in unlocking the answer!

How long should I wait before asking for help?

This is one of the trickiest parts. Spending too little time on trying to solve a problem blocks us from practicing and/or learning problem solving, but taking too long or never asking for help can hold a timeline or team back (I'm definitely in the latter camp myself, (maybe even to this day a little (working on it!))).

One piece of advice I was given early was to be consistent in how long I wait. Of course, this can vary by team, project, and other factors, but my rule of thumb is to give something half an hour before reaching out.

How to ask for help

Asking for help involves bringing an outside person into the context you're in. Doing so effectively is critical to maximize the help you're about to get.

This involves things like:

Asking pointed, narrow questions: If you come to someone and open with "this doesn't work, could you please take a look?" is very different from saying "I'm having some trouble logging in since updating to the latest devise gem, could you please take a look?"
Sharing what I've tried: To save time, it helps if I share with the person who's helping me what I've already tried, to not spend time on those.
Reproducing the problem: It's also good to have a set of steps handy so that if this is an asynchronous or remote request for help, that the other person can try it out and confirm that there's indeed an issue. In fact, we're working on tools to help you visualize your code easily and bring up those reproductions. If interested, do consider signing up for our free beta!

Pairing

If possible, when reaching out for help, it's so helpful to practice pair programming. Most likely, if receiving help, you'll be driving, meaning you'll be doing the coding, but you could also be navigating, meaning you'd be giving tips as your helper as they drive.

Having established the problem, communication is critical to ensure a successful pairing session. More on pair programming coming soon!

Let's be clear, it's ok to get stuck

In an instance of "do as I say, not as I do": I often panic when stuck. Impostor syndrome sets in, and I start wondering if I've ever been a competent engineer.

As engineers, trying to solve new problems or trying to integrate solutions into existing ones is a tricky matter!

One thing that I try to keep in mind when working on a problem is that it will eventually be resolved, and that patience is key. We will eventually reach that "Aha!' moment where everything will click.

What about you? How often do you get stuck? How long do you wait until reaching out for help? We'd love to hear from you! Hit us up on Twitter or email us devrel[at]codesee.io.

Announcing the CodeSee Emerging Developer Track

Nahrin Jalal — Thu, 08 Jul 2021 14:27:29 +0000

As a team largely comprised of self-taught developers and educators, we've noticed a plethora of technical tutorials for beginners at the start of their tech journey and for those well-established in their careers. However, we've also seen significant gaps in the information available for folks looking to get into their first jobs in tech and/or be successful in those first years of that role.

With CodeSee's Emerging Developer Track, we hope to bridge those gaps and empower folks with the resources needed to develop core skills, build confidence, and advance professionally.

What Are Emerging Developers?

We have classified folks preparing to end their studies and start looking for a job, up to folks through their early years in work in tech, as emerging developers. If you are in this "advanced beginner" stage, our resources were created with you in mind.

What Will You Learn?

You can look forward to weekly blog posts and live streams, video tutorials, infographics and visuals, challenges, and opportunities to expand your knowledge with insights from industry guests. Our content will span across platforms and allow you the opportunity to ask questions, seek support, and engage with our team. Each week, we will deep-dive into various key topics, such as:

How to Get Unstuck
Finding Your First Job in Tech
Top Mistakes New Developers Make and How to Avoid Them
Understanding Your First Real-World Codebase
Getting Started With OSS Projects
How To Get the Most Out of Pair Programming
Ways to Ace Your First Year as a Developer
Best Practices: Code Reviews
Introduction to Software Architecture
And much more!

We recognize any piece of content is best as a conversation. Whether you're new to tech, a student, or a long-time developer, we hope you'll share with us your experiences, lessons learned, and advice for others. Drop us an email at devrel[ at ]codesee.io or chat with us in real-time on our streams—we would be delighted to hear from you.

Meet the Team

Staff	Introduction
	Jessica Rose is a longtime tech educator passionate about access to technical education and meaningful work in tech.
	Ramón Huidobro is a web/macOS/mobile software dev and community organizer based in Vienna, Austria. He's spent a lot of his time mentoring, coaching and introducing folks on their development journey, as well as previously ran an after-school coding club to introduce children to programming..
	Nahrin Jalal is a developer, educator, and community organizer based in Toronto, Canada. She is passionate about building inclusive communities, addressing real-world needs with pragmatic software solutions, and creating technical content accessible to all skill levels.

Join Us!

To fully immerse yourself in the CodeSee Emerging Developer Track, be sure to:

Stay tuned on Twitter to be informed of new content and all that we have planned
Follow us on Twitch to catch our jam-packed weekly streams
Subscribe to our YouTube channel to never miss out on innovative video tutorials

We could not be more excited to support you in your tech journey. We hope to see you online! 👋

At CodeSee, we are committed to helping you understand codebases. In just 5 clicks, CodeSee will generate a self-updating visual map of your codebase's dependencies, providing you with a single source of truth for your entire system. For exclusive beta access, sign up to join the waitlist.

The Value of Reading Code

Carmen Huidobro — Wed, 28 Apr 2021 03:58:34 +0000

It’s not just you: Writing code is way more fun than reading it! Taking the time to read, process and understand a piece of code let alone a codebase can take heaps of work.

That said, as codebases grow in size and complexity, as dependencies increase and adapt over a project’s lifetime, it becomes significantly more cumbersome to effectively read them, but at the same time all the more important to keep track of where critical pieces of functionality lie.

Why read code?

Seeing the ways different folks go about solving different problems helps add perspective to our problem-solving approaches.

What cemented this for me was my experience as a kids’ coding coach. The way they have fewer assumptions of how code should work really helped me appreciate different folks’ experiences and try out new thought processes.

Building with our knowledge being exposed to that of others is one of the fundamentals behind the theory of elementary learning called constructionism, which is that of using the context of our understanding to build mental models and building upon them with others. It argues that the media through which we learn is just as important as the learning itself. By being exposed to the code of others, it influences the code that we write.

Here are some techniques I’ve picked up over the years to effectively read code:

Go through the dependencies

Is your codebase a JavaScript one? Let’s open up the package.json file. See some dependencies you recognize? React, Vue, Svelte, perhaps? It also helps to see what scripts are available. What does the build process look like, seeing that we’re using, say, Babel or ESBuild?

Looking at this information can tell us a lot about what to expect when understanding a codebase. For example, some things I’ll look at include, say if it’s a web app, what version of Webpack is being used? Is Webpack being used at all instead of, say, Rollup? What version of Node.js is required? Is it running React version 16 or 17?

We can try the same for the Gemfile if it’s a Ruby codebase, or the Cargo.toml one if written in Rust. This is a great entry point for seeing what makes a codebase tick!

Run the code

This might seem counterintuitive if we’re trying to read the code, but in my experience I find that just doing the work to get the code up and running, debug any issues that might come up with trying to get it running locally for me helps loads with understanding what the code is doing.

It’s possible that trying to run the code will throw up an error. Maybe it’s because we’re trying to run the code on an unexpected setup, or a less-supported web browser. This could even lead to finding unintended issues. Focussing in on these areas helps to build a mental model of what’s going on in a codebase.

It’s also possible that the code will run on the first try, and we can jump right in and start testing specific parts of it. Here, we can use our debugging system, be it the browser’s devtools (as seen on Firefox or Chrome), LLVM for native apps, or using breakpoints in our IDE (I still do plenty of print statement debugging, myself!) to navigate calls made by the codebase during running and see how it all fits together. Stepping through the code by trying out functionality and debugging helps us understand how these pieces fit together, too!

This is an angle of understanding we’re aiming to tackle at CodeSee, letting you record which sections of your code get called up. ‍

Checking out the test suite

A well written test suite should give you a bird’s eye view of what a specific module or functionality set is meant to do. The test author is essentially telling us what they expect the implementation being tested to do. We can use this as a basis for building an understanding of that module.

I find it helps to first take a look at any feature/system tests and then narrow down into individual modules’ unit tests, depending on whether these are available of course. Your mileage may vary, of course. I tend to opt for an outside-in approach.

It does happen that some parts of a codebase will be missing testing coverage. This is a good opportunity to try writing some. Let’s say, for example, we have a module called NumberToHex that converts decimal numbers to hexadecimal. It is, however, untested. This is an opportunity for us to write some tests, understanding what we expect this converter to do, to test that 5 will be converted to 5, that 10 will be converted to 16, and so on.

This can motivate us to try and look at, say, a module, and how we can unit test it effectively, building that understanding. And hey, this also can be a handy contribution to that codebase!

Piecemeal refactoring

To be clear, this is by no means a suggestion to rewrite an entire module, codebase, or anything like that! But if a piece of code is proving hard to read for you, maybe doing a quick refactor can help with understanding it. If there are tests to support you along the way (or that you wrote, see the previous section), all the more safer the feeling!

Doing things like breaking down a large function into smaller ones can go very far toward helping understanding a piece of code much better!

Pairing

If someone who is familiar with a particular piece of code is available, there’s no loss in asking them to walk you through it! Benefits go both ways:

As the person guiding someone through the code, articulating the decisions made towards it helps improve the understanding of the code you wrote.

As the person being guided, you have a great opportunity to ask questions, offer constructive feedback, and even work on a contribution together!

And those are just some techniques!

Regardless of your level of experience, taking the time to read others’ solutions can go a long way towards boosting your understanding of a codebase. Following are some other points of view on the same topics that helped shape some of the above ideas, from Alan Skorkin and Mathis Garberg.

Ultimately, being exposed to different problem-solving styles helps us grow as software builders. But we’d love to hear from you! Do you have any techniques you’ve picked up for making the code-reading process smoother? Hit us up!