Forem: Frank Meza

Some examples of Rust Lifetimes in a struct

Frank Meza — Wed, 17 Jun 2020 06:32:31 +0000

So, you've decided to deep dive into Rust lifetime parameters. Nice!

Let's talk about when dinosaurs roamed the earth.

SIMPLE CASE, COMPILER APPROVED ✅

#[derive(Debug)]
struct Earth {
    location: String,
}

#[derive(Debug)]
struct Period {
    age: String,
}

#[derive(Debug)]
struct Dinosaur {
    location: Earth,
    period: Period,
    name: String,
}

fn main() {
    let montana = Earth {
        location: String::from("Montana"),
    };

    let jurassic = Period {
        age: String::from("Jurassic"),
    };

    let t_rex = Dinosaur {
        name: String::from("Tyrannosaurus Rex"),
        location: montana,
        period: jurassic,
    };

    println!("{:?}", t_rex.name);
    println!("{:?}", t_rex.location);
    println!("{:?}", t_rex.period);

    // compiler disallows these next lines, why?
    // println!("{:?}", montana); 
    // println!("{:?}", jurassic); 
}

Our aim here is to create a Rust compiler-approved Dinosaur struct, incorporating Earth and Period structs. This is what we have after a first pass of putting some props into a few struct objects.

At the bottom of the snippet is a commented-out line that the compiler does not allow. Why? Because montana and jurassic are now owned by t_rex and access to their values is now only allowed via t_rex. This is not how we want the code to behave.

Some more change is left to be done with the code, but this is the basic idea. We want a dinosaur to have knowledge of its location and its time period... but definitely not for the struct itself to own the Earth and Period structs.

SLIGHTLY LESS NAÏVE APPROACH, NOT COMPILER-FRIENDLY YET ❌

Now let's say you decide to start experimenting with Rust references and come up with this idea:

struct Dinosaur {
    location: &Earth,
    period: &Period,
    name: String,
}

But even before running any business logic between the structs, the compiler already wants to know more, it wants explicit lifetime parameters on Dinosaur, so you dig around and put this together:

LIFETIME PARAMETER INFORMED CASE, COMPILER APPROVED ✅

this lifetime snippet in a Rust sandbox

#[derive(Debug)]
struct Earth {
    location: String,
}

#[derive(Debug)]
struct Period {
    age: String,
}

// instead of receiving the values `location` and `period`,
// Dinosaur borrows (pre-existing) instances of Earth, Period
#[derive(Debug)]
struct Dinosaur<'a> {
    location: &'a Earth,
    period: &'a Period,
    name: String,
}

fn main() {
    let montana = Earth {
        location: String::from("Montana"),
    };

    let jurassic = Period {
       age: String::from("Jurassic"),
    };

    let t_rex = Dinosaur {
        name: String::from("Tyrannosaurus Rex"),
        location: &montana,
        period: &jurassic,
    };

    println!("{:?}", t_rex.name);

    println!("ACCESSING MONTANA DIRECTLY {:?}", montana); 
    println!("ACCESSING JURASSIC DIRECTLY {:?}", jurassic); 
}

In a nutshell:

Dinosaur is receiving location and period as borrowed references.
Since Dinosaur does not own the values, the Rust compiler wants explicit confirmation that the original value that the references refer to will still be valid as long as Dinosaur needs them.
This explicit confirmation comes in the form of lifetime parameters, on Dinosaur<&'a>.

HANDLING SEVERAL LIFETIMES IN A SINGLE STRUCT

"But why doesn't each prop in Dinosaur gets its own letter? What about this <'a, 'b> that I saw somewhere on Stack Overflow? How does that work?"

Oh, you mean something like Dinosaur<'a, 'b> , right? So each of the letters represents a different scope that the struct knows about. Here is a link to the official documentation, but the important part of it right now is the following snippet, illustrating what the lifetime parameters signify in terms of scopes.

{
    let r;                // ---------+-- 'a
                          //          |
    {                     //          |
        let x = 5;        // -+-- 'b  |
        r = &x;           //  |       |
    }                     // -+       |
                          //          |
    println!("r: {}", r); //          |
}                         // ---------+

I'll leave integrating this stuff into our Dinosaur example up to you, o dear reader of mine.

Keep Calm And Carry On Coding: What to Do When Requirements Change

Frank Meza — Fri, 06 Mar 2020 00:45:40 +0000

Envision the following scenario: you are working away at the final 5% of a project, glad to be near the end, when you catch the first hints of unexpected changes coming in the near future.

Your chat channel starts to fill up with innocuous phrases like "next iteration" and "looks good, now let's see how the users respond." It seems harmless, until you begin to receive successive waves of PDF files with pages upon pages of new requirements. “Huh…,” you might think to yourself, “this is turning into a completely different application!”

If this is the first or second time you’ve experienced this, you might be somewhat new to the field of software development, and you may be feeling defeated. You want to feel that feeling of completion! Of crossing the finish line. It was so close. And now it appears so far away.

How did this happen? People want to build software. They have a theory about what they want, and what their end users want. The perfect set of features, which will naturally be intuitive, simple and easy to use. But, it's just a theory. Once that theory is tested, it will most likely be only partially correct. That critical feature we built last month? We shipped it! It works perfectly. But, the users don’t understand it, and no one is using it. And so… the requirements will change. The goalposts will move.

Here are some strategies to help you survive this lamentable, all-too-common predicament.

Acknowledge the Emotional Impact

Late stage changes can brew a soul-crushing concoction of emotions.

The first step out of this quagmire is to acknowledge that yes, you are frustrated. It's reasonable to be so. The code you've painstakingly engineered to match the original requirements might be critically maimed by "a few tweaks" in the 11th hour of the project. You feel stranded and overwhelmed. You start to wonder if life could have been easier if you had taken up a simpler career as a stuntman, or even as an astronaut.

The next thing to do? Consciously choose constructive over destructive reactions to this distressing situation.

Say No to Destructive Reactions

You may be tempted to wallow in self pity, or lash out in frustration. But this will only isolate you from the people you need to work with in order successfully navigate those changes. Succumbing to feelings of helplessness or inadequacy is likewise counter-productive, as that will blunt your ability to confidently rewrite or even discard code that no longer makes sense. Finally, a total emotional disengagement from the project may temporarily insulate you from feeling bad, but apathy will completely block you from any productive work until you get beyond it.

Grow by Facing Tough Times Head-On

Try to adopt the mantra "I grow when challenged". Internalize that hard situations are invaluable for your growth as a software engineer.

Consider an athlete who only trains with other, less capable athletes. While that individual may feel good about their performance, in reality they are capped at their present level of development. Similarly, a workplace devoid of significant and unexpected challenges will be a sterile and lifeless environment, which will stunt your growth as a professional problem solver.

The path to becoming a better software engineer is a narrow one, full of rough patches and at times, very challenging terrain.

Tell Your Rubber Duck All About It

Take a deep breath and step away from your computer. It’s time to make a fresh assessment of the situation, unencumbered by the weight of all that code you've written up to this point.

First, gather up all the information relating to the requested changes. This might include the latest slide deck of changes, previous flow charts that you or a coworker has written, or scribbled notes and pinned chat messages.

Once you've got that organized, the next thing to do is to try and explain to yourself what needs to be done in the simplest terms possible. Describe the present situation, the changes to be made, and the end goal. Using these thoughts as a guide, tour the regions of the system where changes are likely to occur. You might find that when you put a magnifying glass to them, those changes might turn out to be less pervasive than you initially thought.

Finally, pick up a whiteboard marker and present your ideas to your peers. See if you can explain the problem and your proposed solution, using large, broad brushstrokes. Chances are, if you can articulate it, you've got a workable first draft solution.

Practice Paired Planning

Paired planning is a great way to see the changes through someone else's eyes. It's likely that your partner will have a different perspective, and come up with a novel approach, or bring up some edge cases you hadn’t considered. A taste test between several possible approaches is a great way to find a simple, efficient, and correct solution.

Choose Lo-fi When Designing

During the planning phase, your goal should be to generate as many ideas for efficient solutions as possible. Don’t jump headfirst into coding. It's better to spend an hour outlining what you intend to do, explaining it to someone else, and clarifying your understanding. Whiteboard drawings, sequence diagrams, and high level design summaries can be some of your best tools during this process.

With a whiteboard, you can virtually reimplement a system hundreds of times in the same duration it would take to incorrectly refactor the codebase once. The disposable nature of whiteboarding helps to not fall in love and commit to your first idea, which may not be the most optimal solution.

Weigh the Scope of Changes Against Your Budget

Before writing more code, ask the following questions to help guide the process of a refactoring a large software project:

How much tolerance is there in the project schedule? Can we make paradigm shifts, or should we fall back to bandaids until the next release? Can we ask for more time to "do the right thing"?
Given a tight delivery deadline, can the changes be quarantined to a particular layer of the application? For example, in the situation where the UI must change but it's too risky at this point to change business logic, one could build transformation logic to retrofit objects flowing between the UI and the business layers.
Given a more liberal deadline, which other parts of the codebase should we also improve, while we're in here making the essential changes?
Is this an opportunity to clean up the codebase? For example, could we delete logic which models a deprecated requirement? If the answer here is yes, could that be helpful in formulating part of the solution?

Get Up and Take a Break

It's always helpful to stop, take a break, and come back fresh. Move your body, and get outside of your own head for a short while. Do some jumping jacks. Pet a friendly dog. Go for a walk. Go get coffee, enjoy the outside air. Once revitalized, start coding with conviction, and you will prevail.

Accept that Change Is Inevitable In Living Projects

It's several weeks later, and you've finally got a stable release. You matched the designs and the changes in functionality that they requested. Confidently, you submit your work for review. To your surprise, they ask for even more changes. The cycle begins anew.

Actually, this is a great thing! After seeing their vision come to fruition through your labors, and watching how end users react, your product owner better understands what they ultimately need. Based on what you delivered to them already, they can now see how much more is possible. It’s plainly obvious they trust you to make the next set of changes, since you've proven you're more than capable.

So roll up your sleeves, and take the new challenge in stride. Carry on knowing that you are growing though the experience, and validating your ability to deliver software that is a living organism, always changing, always adapting!

"The Value of Code Documentation"

Frank Meza — Fri, 31 Jan 2020 23:02:24 +0000

Code documentation is the collection of easy to understand images and written descriptions that explain what a codebase does and how it can be used.

It can be simple explanatory comments above functions and blocks, or a full-fledged developer handbook, complete with prescriptive style dos-and-don'ts, overviews of each part of the application, and approaches to the most common types of coding tasks.

It's often best to find a happy medium between these two extremes when you make the conscious decision to comment your code and outline the gnarlier areas of a codebase in plain language.

Why document your code?

Why go to the trouble writing about your code, instead of just writing code? Wouldn't that just be more productive anyway?

Mental Save Points

Documentation is like a mental save point for those times when you finally get what's going on at the end of the day and don't want to lose momentum. Well documented code will ensure that when you need to dive back in tomorrow morning (or several months from now), you won't have to take as much time getting up to speed.

Documented code gets reused

The difference between a used library and an unused library often comes down to its documentation.

Who wants to use an undocumented open-source library or contribute to an undocumented project? Almost no one.

In most cases, you'd rather use a less powerful library that has docs. Why? Because the documentation conveys other points of information about a codebase. The developers believe that the project is worth the time and energy to write about it in plain language so anyone who might be interested can quickly get started and learn how it works, and why key decisions were made.

Finding a new, interesting, and well-documented project in your favorite language can be very exciting and fun. Let's look at the extreme alternative: being required to use an undocumented code library and potentially contribute to a seemingly byzantine codebase... it sounds pretty painful, right?

So why haven't you documented your own code?

Documenting code is part of writing good code

A cornerstone of good code is maintainability, achieved through understandable, legible documentation.

There are multiple ways of documenting code:

choosing good names for variables and functions
leaving brief comments within the code to help give context to future readers
adding illustrative images such as sequence and entity relationship diagrams
providing API docs, describing each class, method, argument and return value
using a statically typed language, such as TypeScript (types as documentation)

Compare two examples

Let's say you're getting some data from a backend API and "ingressing" it - converting it into a more useful shape for a front-end UI. Here's the first of two possible solutions.

// wdgt.js

export const converter = (w) => {
    const wdgtHdr = {
        name: w.nm,
        id: w.id,
        ts: w.lastTS
    }

    const wdgtDtl = {
        dtlId: w.dtlId,
        dtlName: w.dtlNm,
        openTS: w.oTS,
        closeTS: w.cTS
    }

    const wdgtRev = w.revs.map((r) => {
        const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r
        const rr = {
            assocId: prsn1Id,
            assoc: `${prsn1Fn} ${prsn1Ln}`,
            amount: amt,
            note: note,
            revTS: cTS,
        }
        return rr
    }

    return {
        wdgtHdr, wdgtDtl, wdgtRev
    }
}

The above code has the potential to be painful. You can see by the name that this is some sort of converter that takes w as its param.

It looks like it returns a header, maybe details, and something called revs. Where did revs come from, anyway? Of course, there's no details about the incoming variable names note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS... or is there? Is rr short for returned rev? Who can say.

Let's look at the second example.

// widget_utils.ts

// widgetConverter :: widgetRespDTO -> widget
export const widgetConverter = (wResp: widgetRespDTO): Widget => {
    const widgetHeader: WidgetHeader = {
        name: wResp.nm,
        id: wResp.Id,
        ts: wResp.lastTS), // timestamp
    }

    const widgetDetail: WidgetDetail = {
        id: wResp.widgetId,
        name: wResp.dtlNm,
        openTS: wResp.oTS, // timestamp
        closeTS: wResp.cTS // timestamp
    }

    // [WidgetRevisionsRespDTO] is nested inside of WidgetRespDTO

    // [WidgetRevisionsRespDTO].map -> [WidgetRevision]
    const widgetRevisions: ReadonlyArray<WidgetRevision> =
        wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => {
            // how that other team names their variables...!
            const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs

            const comment: string = cmt
            const associateId: string = prsn1Id
            const associateName: string = `${prsn1Fn} ${prsn1Ln}`
            const amount: number = amt
            const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi

            return {
                associateId,
                associateName,
                amount,
                comment,
                revisionTS,
            }
    }

    return {
        widgetHeader,
        widgetDetail,
        widgetRevisions,
    }
}

Wow, how different! This function is in a util file, so the main file is less cluttered already. It's also written in TypeScript instead of plain JavaScript, so we have the benefit of type definitions to help guide us.

We're converting widgetRespDTOs into widgets. Though shortened, we have full knowledge of what wResp is. We're creating a widgetHeader, and a widgetDetail, that's easy to see. We also understand what oTS and cTS are. We can tell WidgetRevisionsRespDTOs are nested inside of WidgetRespDTO.

Someone very kindly renamed the incoming variables so everyone who sees this code knows what they are. Finally, we see a Widget must be composed of the returned {widgetHeader, widgetDetail, widgetRevisions} object, since it must match the return type Widget specified at the top.

Which code would you feel better about using?

Who benefits?

Well documented code benefits many people:

1. Junior developers

Because it's in plain language and easy to understand, documentation helps junior developers and new team members feel confident jumping into a codebase. This prevents frustration and early abandonment of a task because it gets too complicated too quickly.

It's also helpful for junior developers to write their own documentation so they can share their code with others and so they can get a better understanding of their code.

2. Senior developers

By taking the time to document now, senior devs spend less time explaining their code to others in the future.

They can also write more complex code. Plain language documentation lets others use it like a black box, without having to understand the inner workings.

3. Teams & open source projects

Personnel changes can bring a tremendous slowdown to a project. Up-to-date and well documented code can serve as insurance against such slowdowns and allow the remaining team members to take a step back, review the code from a high level and decide on the best course of action moving forward, and if needed, on-board new employees.

4. You

When documenting code, you must summarize it. In order to summarize properly, you must be able to understand it, holding the different parts in your head at the same time. Writing or contributing to the documentation is a shortcut to really understanding a codebase, making huge contributions, and feeling like a great part of a great team.

Good documentation can DRY up our coding experience

As a programmer you've probably heard of the Don't Repeat Yourself principle as a key to writing clean and concise code. Instead of repeating the same code block several times, write a function that can be written once and employed all over your application.

In the same way, you and your team shouldn't be running into similar problems and then reinventing the wheel each time you attempt to solve them. For example, have you ever heard one of your coworkers or found yourself saying:

"Agh, I solved something very similar to this but I never remember how I do it when it comes up... I should probably write it down somewhere, huh?"

You then find yourself scanning the same Stack Overflow threads again and again.

Save yourself and your coworkers this grief by following the spirit of the DRY principle and writing a document that you can employ every time the issue comes up! This will help you and others on your team save time, and be more effective in writing simpler, more manageable, and more efficient code.

How has code documentation, or the lack thereof, affected you?