software-engineering 12 min read

Elevate Your Code: my FOSSConf'23 keynote at IIIT Delhi, written up

The written version of my FOSSConf'23 keynote at IIIT Delhi: naming, comments, nesting, SOLID, YAGNI, DRY vs WET and async Python, all with hands-on code, from a deck that ran in the terminal.

Today I gave a keynote at FOSSConf’23, organised by the folks at FOSSCU, in the main hall at IIIT Delhi. The title was “Elevate Your Code // Practical Insights for 10X Impact”.

I’d been looking forward to this one since early November, when I opened my announcement tweet with a terrible joke: what’s a FOSS developer’s favourite movie genre? Open-source-cery, because they love a bit of magic that everyone can contribute to. 🪄 I’m not sorry.

Last night I promised to share some resources for those who couldn’t make it, so here they are. The slides and every code sample are on GitHub, and this post is the version with me talking over them.

A small confession about the slides: there are no slides. Well, there’s no PowerPoint. The whole deck is a Markdown file that I ran in the terminal with mdp, and I switched to the editor for the code. It felt right for a FOSS conference, and it meant the deck and the code lived in the same repo. The “Final changes” commit went in at 1:45 AM last night, which is about as on-brand as it gets. :P

Here’s the whole thing, rendered slide by slide:

Me at the IIIT Delhi podium in a grey hoodie, laptop open, with the FOSSConf'23 standee beside me and the terminal deck up on the big screen
At the podium in the main hall, from FOSSCU’s photo.

$ whoami

The usual intro first: the road from intern at Webyog to principal engineer at Atlassian, and a slide on life outside work (motorbiking, fountain pens, mechanical keyboards, too much homelab tinkering, photography and chess again after a decade off).

A slide titled "Quick intro about me" with two images: a winding career timeline from Webyog as intern through Adobe, Shuttl, Synaptic and Uber to Atlassian as principal engineer, and a collage of hobbies with motorbikes, fountain pens, two mechanical keyboards, a homelab desk, a grid of photographs and a chessboard

Then a word for the hosts. I really appreciate what FOSSCU is trying to do. One of the best ways to set yourself apart from the crowd is to contribute to open source.

I warned the room it would be mostly hands-on code and as technical as I could keep it, did a quick census (students, working professionals, and who has actually raised a PR in the last two weeks), and told everyone to interrupt me with a raised hand. Python was the language of choice, but nothing in the talk is Python-specific.

So, what is a 10x engineer?

I started with the title, because “10X” is a loaded word and I didn’t want anyone thinking I meant the person who types fastest.

A slide asking "So, what is a 10x Engineer?" above the xkcd Real Programmers comic, where programmers argue nano, emacs, vim, ed and cat before one claims real programmers use butterflies
Obligatory xkcd. Real programmers use butterflies.

The definition I went with: someone who consistently delivers ten times more value than their peers. Not just technically skilled, but a problem solver who sees the big picture, understands how different systems relate to each other, and comes up with ways of doing things that scale well.

A slide with four centred lines: a 10X engineer consistently delivers 10 times more value than their peers, is not just technically skilled, sees the big picture and the complex relationships between systems, and finds new ways of doing things that scale well

So it’s clearly not just about writing code. It’s about code that is scoped well, can be extended, can scale, can be collaborated on and is documented. And the one line I’d like people to remember from the whole hour: you cannot scale without a team.

The agenda went from the basics (craftsmanship), to principles, to the balancing act between them, to a couple of paradigms, and then some wisdom from the principal engineer side of things.

Naming things

There’s a very popular quote you’ve all seen on a sticker somewhere:

A slide with a quote block: "There are only two hard things in Computer Science: 1. Cache invalidation, 2. Naming things!", attributed to Phil Karlton

Cache invalidation can wait for another talk, so naming went first. These are the pitfalls I keep seeing in code reviews. Here’s the first file I opened, and it had a failing test:

class o:
    def __init__(i, p, q, t, s):
        i.p = p
        i.q = q
        i.t = t
        i.s = s

    def calc(i):
        c = i.p.pr * i.q
        c += c * i.t
        c += i.s
        return c

def util_calc(p, q, t, s):
    return p.pr * q + p.pr * q * t + s

Go on, find the bug. What’s t? What’s s? Why is self called i? You can’t debug what you can’t read.

The worst way to “fix” this is to sprinkle comments over it, # tax rate next to i.t, # shipping cost next to i.s, and call it a day. The names are still p, q, t and s, and nothing stops those comments from going stale. In the version I committed after the session, those same comments say # discount and # super discount. The code didn’t change at all, and the comments are now lying to you. Python didn’t complain once.

The fixed version, Order with product, quantity, tax_rate and shipping_cost, and util_calc renamed to calculate_order_total, reads like a sentence. And with real names, the bug is easy to spot: the test asserts that 5 units at 20 with 5% tax and 5 shipping cost 70. It’s 110.

A slide listing what the good version fixed: avoid single-letter names, don't abbreviate, don't put types in names, include units in names, be careful with naming conventions, rethink the name if you're struggling, and organise code logically
Every point here is in the diff between 0_bad_code.py and 2_good_code.py.

“Rethink naming if you’re struggling” is my favourite one. If you can’t name a function, it’s usually doing two things, and util_calc is the classic case.

How not to comment

Which brought us to comments. The second example was a tiny library system: a class b for books, a class m for managing them, a method chk_old, and a util(x, y) with the comment # Complex logic, DO NOT TOUCH!. Every line had a comment, and none of them helped.

The cleaned-up version removes the comments that only say what the code does, replaces the magic 2000 with OLD_BOOK_YEAR_THRESHOLD, and pulls the scary condition out into a function whose name says what it means:

def is_eligible_for_discount(quantity, price):
    quantity_condition = (quantity * 2) > DISCOUNT_QUANTITY_THRESHOLD
    price_condition = (price - 3) < DISCOUNT_PRICE_THRESHOLD
    return quantity_condition and price_condition

Descriptive names do the explaining, the code becomes the specification, and the few comments that survive explain why (like what a constant is for), never what. Then I showed the final file with all the comments gone, and it looks so much cleaner.

Nesting syndrome

Now, the thing that really grinds my gears in code reviews.

A slide: "Now, let's shift gears! You know what grind my gears while reviewing code? Nesting!" followed by a heading in capitals: LOADS OF NESTING!

The example was a process_user_data that checks for a name, an age over 18, an email on the right domain, an address and a city, with every check one level deeper than the last. Eight levels of if, and the else for the very first check sits more than 20 lines below it. Good luck matching those up in a review.

The first fix is early returns, also known as inverting the conditions. Handle each error upfront and get out:

def process_user_data(user_data):
    if user_data is None:
        return "No user data provided."
    if 'name' not in user_data:
        return "Name is missing."
    if 'age' not in user_data:
        return "Age is missing."
    if user_data['age'] <= 18:
        return "User is underage."
    # ...email, address and city checks...

    return "User data is valid."

Same behaviour, flat, and you read it top to bottom. The second step moves all the checks into a separate validate_user_data that raises a ValueError, so process_user_data only does the processing and catches the error. One function validates, one function processes.

S.O.L.I.D.

Then I asked the room for the most overused, most popular set of principles in programming. Yep, you guessed it right.

A slide with the heading S.O.L.I.D. and the five principles listed: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation and Dependency Inversion

I’m not here to bore anyone with theory, so it was code again. An OnlineBookStore class that stores books, searches them, processes payments and delivers them, all in one place.

The better version splits payment and delivery into a PaymentProcessor and a DeliveryService, and the store only manages books. The “absolute best” version goes all the way: a BookRepository, abstract PaymentProcessor and DeliveryService with concrete subclasses like CreditCardPaymentProcessor and HomeDelivery, and a store that takes all three in its constructor:

class OnlineBookStore:
    def __init__(self, repository, payment_processor, delivery_service):
        self.repository = repository
        self.payment_processor = payment_processor
        self.delivery_service = delivery_service

    def purchase_book(self, title, user):
        book = self.repository.find_by_title(title)[0]
        self.payment_processor.process_payment(book, user)
        self.delivery_service.deliver(book, user)

A slide titled "What did we change to write the absolute best code?" mapping each SOLID principle to the code: each class has one responsibility, payment and delivery are extended without modifying existing code, the store can use any subclass, interfaces are specific, and the store depends on abstractions

Want PayPal? Write a PayPalPaymentProcessor and pass it in. The store never changes.

Is “good” code always good?

And then the ultimate question: is the “good” code always good, or is it just ideal code? Can the “better” version actually be good enough? The bad version’s file in the repo even ends with the comment # Is it really bad though?. Nine classes to sell one copy of 1984 is a lot of ceremony.

A centred slide: the heading Y.A.G.N.I. and below it, "You Ain't Gonna Need It!"

Premature optimization is one of my favourite topics to talk about at work. I even wrote an internal blog on it, and I may publish it externally soon. Earlier this year I also wrote about a close cousin of it, coding the shortest path from A to B first.

Discussions about performance are often premature, and they distract from what matters more early on. Performance has to be balanced with velocity (how fast you can add features) and adaptability (how easily the system can change for new requirements). Think of any project in stages: 0 to 1, 1 to 10, 10 to 100. The problems at 10 to 100 are not the problems you have at 0 to 1.

Facebook started on PHP, took the criticism, shipped fast, and fixed the performance problems when they actually became problems. A lot of open source came out of that later.

The code for this was an AdvancedFileProcessor with a “complex hashing algorithm” for file IDs, a sorted list with bisect for binary search, and a cache on top. Unless that’s in your spec and documented, it’s a perfect example of what not to write on day one. The KISS version is a class with one dictionary: if the path is in it, return it, else process and store. Good enough, and you can optimize it later if you ever need to.

I see this in interviews a lot too: a candidate forgets the original scope of the question and goes on to build something super complex.

The smaller example was finding unique numbers in a list. One version builds a set in a loop “for optimization”, the other is just this:

def find_unique_numbers(numbers):
    return list(set(numbers))

It’s more readable and still efficient for most practical purposes. Optimizations can be useful, but apply them judiciously and in context. Over-optimizing gives you code that’s harder to read and maintain without a significant performance benefit.

W.E.T. vs D.R.Y.

Similar story. Write Everything Twice vs Don’t Repeat Yourself. The DRY file had three tiny functions, calc_area_rectangle, calc_area_circle and calc_area_triangle, each called exactly once. The WET file just did the maths inline in three lines. Which one is better?

It depends! 😅

A slide with two headings. DRY: reduces redundancy, improves maintainability, avoids bugs. WET: simplicity in early stages, avoids premature abstraction, learning and experimentation

In practice a balance works best. Over-apply DRY and you get premature abstraction, too much WET and you get a codebase that’s painful to update.

Sync vs async

Time check! There was enough left for one more favourite topic: asynchronous vs synchronous programming. I asked the room for the difference, then showed a demo.

Both scripts fetch https://httpbin.org/delay/2 five times, an endpoint that waits two seconds before responding. The sync one uses requests in a loop, so it waits for each call before starting the next, and it can’t finish in under 10 seconds. The async one fires all five at once:

async with aiohttp.ClientSession() as session:
    tasks = [fetch_url_async(session, url) for url in urls]
    responses = await asyncio.gather(*tasks)

and should finish in a bit over two.

A centred slide: "But isn't Python Single Threaded as GIL limits it?" and below it, "Well, the answers is in your Kitchen! Hear me out!"

The GIL question always comes up. The slide only promises that the answer is in your kitchen, so here’s the kitchen version for anyone who wasn’t in the room: one cook can put the rice on, and while it boils, chop the onions and start the dal. Nobody is cooking faster, the cook just doesn’t stand there staring at the pot. That’s async. It’s one thread anyway, so the GIL doesn’t get in its way, and the waiting (for the network, for the disk) isn’t Python’s work to begin with. Hiring more cooks is multi-processing, and that’s what you need when the work is actually CPU-bound chopping. Which led straight to the next question for the room: what’s the difference between multi-threading and multi-processing?

As you grow in your SWE journey, the underlying hardware and OS concepts start to matter a lot, because your job slowly moves from writing code to designing scalable systems.

A centred slide listing concepts one per line: Paging, Virtual Memory, Cache (L1 vs L2), Disk I/O, IPC (Inter-Process Communication) and Networking (OSI model?)
Homework.

Everything we covered is the tip of the iceberg. But if you bring even some of it into your daily coding, it shows, in code reviews and in interviews. Being someone people want as a teammate is the most low-hanging fruit there is.

Outro: who is a principal engineer, btw?

I’d asked ChatGPT too (the screenshot is in the repo), and it gave a very sensible answer about technical leadership, mentoring and stakeholders. The GIF on the slide is closer to the truth.

A slide titled Outro asking "Who is a Principal Engineer btw?" with the This is fine meme: a cartoon dog sipping coffee in a room on fire, in front of a blurred collage of work screens
This is fine. (The work screenshots behind the dog are blurred here.)

In all seriousness, it’s delayed gratification. Context switching goes to 101%. Coding is no longer the priority, though I still try. There are meetings galore. And you have to get comfortable with uncertainty.

A slide titled "In all seriousness:" with five points: delayed gratification, context switching to 101%, coding is no longer a priority but I still try to code, meetings galore, and becoming comfortable with uncertainty

Wrapping up

Then it was Q&A, with a “Go on! Ask me some spicy questions?” on the screen, and a thank-you slide with a QR code drawn in Unicode blocks that takes you to my X profile. Thanks for the questions, the hands that went up mid-talk, and everyone who stopped for a photo after.

After my session I stayed for the Women in Tech panel, where the panelists talked about how they got started in their careers. Super inspiring stuff. Kudos to FOSSCU for putting it on, and for the whole event. 🙌

If you want to try any of this, clone the repo. Every section is a folder, from 1_naming_things to 7_async_vs_sync, with the bad, better and good versions numbered in order, and the deck is 0_SLIDE_DECK/slides.md. Install mdp (apt or brew), run mdp 0_SLIDE_DECK/slides.md, and you get the talk exactly as the room saw it. The naming example still has a failing test in it, on purpose. Go fix it. :P

Elevate Your Code // Practical Insights for 10X Impact, slide 1 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 2 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 3 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 4 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 5 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 6 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 7 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 8 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 9 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 10 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 11 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 12 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 13 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 14 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 15 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 16 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 17 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 18 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 19 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 20 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 21 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 22 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 23 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 24 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 25 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 26 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 27 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 28 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 29 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 30 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 31 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 32 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 33 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 34 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 35 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 36 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 37 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 38 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 39 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 40 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 41 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 42 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 43 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 44 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 45 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 46 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 47 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 48 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 49 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 50 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 51 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 52 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 53 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 54 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 55 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 56 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 57 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 58 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 59 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 60 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 61 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 62 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 63 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 64 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 65 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 66 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 67 of 68Elevate Your Code // Practical Insights for 10X Impact, slide 68 of 68
1 / 68
The full deck, all 68 slides, rendered from the Markdown file I ran in the terminal with mdp. Use the arrows or swipe.
jatinkrmalik/FOSSConf-23-Keynote Slides (mdp Markdown) and all the sample code from my FOSSConf'23 keynote, Elevate Your Code // Practical Insights for 10X Impact. Python ★ 7 View on GitHub →

Comments

    Supports `code`, ```blocks```, **bold**, *italics* and links.

    Keep reading