Darko Tasevski — Writing

A Case Against Abstraction

Wed, 03 Sep 2025 00:00:00 GMT

Recently, I was knee-deep in a very complex project. The problem wasn't just the size of the codebase, it was the endless forest of indirection. Factory functions, Providers, Managers, Registries, Mixins; everywhere I turned, there was another layer. Following the flow of data felt less like tracing logic and more like spelunking through a cave system with no map.

At one point, I leaned on an LLM to help me debug. And it failed. Not because the model was weak, but because the architecture was so fragmented and implicit that even an AI couldn't piece it together. Abstraction, the thing we've always leaned on to tame complexity, had itself become the source of complexity.

In this specific case, abstraction didn't clarify; it obscured. For both me and the AI.

Yesterday's Cure, Today's Disease

"Sufficiently advanced abstractions are indistinguishable from obfuscation." — @raganwald

Historically, abstraction was our main defense against cognitive overload. Humans only hold so much detail in working memory, so we built neat layers that hid what we didn't need to see. Encapsulation, state management, factories, etc. they weren't just patterns, they were survival mechanisms.

But in the AI era, the tradeoffs have shifted.

We hit cognitive limits quickly, while an LLM can plow through raw detail without ever getting tired.
What they can't handle is fragmentation. Implicit behavior scattered across dozens of files. Context broken into 15 layers of indirection.

The result? Abstraction no longer reduces cognitive load. It multiplies it. It takes effort that should go into problem-solving and reroutes it into archaeology.

Case Study: When the Russian Dolls Collapse

Note: The project details and code samples in this case study have been obfuscated and anonymized. The patterns, complexity, and architectural issues described here are real, but the identifiers and structures are adjusted so the example remains relatable without exposing proprietary code.

To see how this plays out, here's a snapshot from a real-world TypeScript/React project I worked on. It's not a hypothetical; it's a cautionary tale of what happens when abstractions pile up unchecked.

40,000+ files in total, ~5,800 lines in core files
233+ files matching abstraction patterns (Providers, Managers, Factories, Handlers)
20+ Redux reducers with complex interdependencies
15+ mixin compositions in the components layer
State object with 80+ properties, spanning UI, business logic, networking, and persistence
800+ unit test files with 200-400 lines each
200+ E2E test files with 300-500 lines each

Abstraction Layer Explosion

A simple user action could bounce through a chain like:

User Action 
→ Component
→ Action
→ Reducer
→ Manager
→ Provider
→ Backend

That's not architecture, that's bureaucracy. Debugging usually requires going through at least 6 to 8 files just to locate the root cause.

Example chain:

    Some data
  → DataManager
  → DataProvider
  → EntityManager
  → StateManager

Each layer existed to "decouple", but the combined effect was Russian-doll indirection where nothing was visible without peeling back four wrappers.

Custom Frameworks on Top of Frameworks

The team even rolled its own inheritance system to work around Immutable.js limitations:

class BusinessEntity extends InheritableImmutableRecord {
  static defaultValues = {
    id: null,
    name: '',
    config: Map(),
    state: Record({}),
    // ... 80+ more properties
  }
}

mergeImmutableRecordDefaults(BusinessEntity)

This meant every developer had to understand:

Immutable.js internals.
The custom inheritance layer.
The domain logic built on top.

The implicit behavior was so deep that neither humans nor LLMs could reason about it without constant back-and-forth exploration.

State Bloat

The main app state was a monolith with 80+ properties across unrelated domains:

interface ApplicationState {
  containers: List<Container>
  totalContainers: number
  dataItems: Map<ID, DataItem>

  // UI state
  containerRect: Rect
  scrollbarOffset: number
  isDebugModeEnabled: boolean

  // Business logic
  formFields: Map<string, FormField>
  attachments: Map<string, Attachment>
  validationErrors: Map<string, ValidationError>

  // Connection state
  connectionState: ConnectionState
  apiService: ApiService | null

  // ... 60+ more properties
}

Any change meant wading through 500+ lines and dozens of imports. New developers were paralyzed, and AI assistance was worse than useless, it would hallucinate or give superficial answers because it couldn't hold the whole structure in context.

Pattern Proliferation

Each entity type copied the most complex existing pattern:

FormFieldManager + FormFieldProvider + FormFieldValueManager + FormFieldValueProvider
DataManager + DataProvider  
BookmarkManager + BookmarkProvider
CommentManager + CommentProvider

The result was not reusability but 4x duplication with inconsistent interfaces. Even if an LLM parsed one chain, knowledge didn't transfer to others.

When LLM Models Hit the Wall

This over-abstraction wasn't just hard for me. It crippled my ability to collaborate with AI.

Context fragmentation: A single feature spanned 20+ files and thousands of lines, more than even the largest context windows can practically handle.
Implicit flows: State changes rippled through hidden chains like:

dispatch(updateEntity(entity))
  → entityReducer updates state
  → EntityManager.validateEntity()
  → EntityProvider.syncToBackend()  
  → DataManager.handleChange()
  → StateManager.notifySubscribers()
  → Multiple UI components re-render

No LLM could trace that end-to-end without losing coherence.

Scattered logic: Validation in Models, error handling in Reducers, sync logic in Providers. No single place contained the truth.

Observed impact:

Bug diagnosis took 8-10x longer.
LLM explanations were 70-85% less accurate.
Refactoring suggestions were blocked by tangled dependencies.
Average time to onboard a new developer: 3-4 months (vs. 2-3 weeks in cleaner codebases)

The architecture didn't just slow humans, it actively blinded AI.

Test Suite Complexity and Flakiness

You might think: "Well, maybe the AI could still piece things together from the test suite." Unfortunately, no. The tests were just as over-engineered as the production code and far more fragile.

Thousands of tests existed, but instead of providing confidence, they became a constant source of pain.

Why the Tests Were a Crisis

Massive mocking requirements: Testing DataManager meant mocking 6+ dependencies plus an entire 80-property state tree.
Timing-dependent abstraction chains: Async flows cascaded through Managers, Providers, Reducers, and event emitters. Slight variations caused flakiness.
Implicit synchronization: Tests failed unless state propagation across 5+ abstraction layers happened within arbitrary timeouts.
Retry culture: E2E tests routinely required retries and 30-second waits, masking systemic fragility.

Example:

// Adding a property to DataManager required updating:
// 1. Manager mock
// 2. Provider mock
// 3. EntityManager mock
// 4. ReducerCallbacks mock
// 5. Component test wrappers
// 6. All fixtures

A "simple" new feature meant updating 10-20 test files.

Quantified Pain

~80% of test runtime was spent on setup, teardown, mocking, and retries, and not actual logic.
Debugging a single flaky test often took 3+ hours.
New developers needed 2-3 months before they could write reliable tests.
Test maintenance overhead: Nearly 50% of development time was spent debugging and keeping tests working.

When Abstraction Actually Works

Before we dive into solutions, let's acknowledge that abstraction isn't inherently evil. There are cases where it genuinely helps:

Good Abstraction Examples

Domain Boundaries: Separating user management from payment processing
Cross-cutting Concerns: Logging, error handling, authentication
Complex Algorithms: When the implementation details would obscure the business logic
External APIs: Wrapping third-party services with consistent interfaces

The Key Difference

Good abstraction reduces cognitive load by hiding irrelevant details. Bad abstraction increases cognitive load by hiding relevant details.

Why Humans + AI Both Need Directness

Humans think better with clarity. AI works better with explicitness. Abstraction, when it hides more than it reveals, hurts both.

In the pre-AI era, abstraction bought us simplicity. In the AI era, abstraction taxes us thrice:

Humans pay in cognitive load.
Machines pay in broken context.
And tests pay in fragility and flakiness.

The best architecture for both is direct, explicit, domain-driven, not endlessly abstracted.

Practical Solutions

Audit Abstractions Like Dependencies

If a layer doesn't clearly earn its keep, remove it.

Before:

class DataManager {
  constructor(private provider: DataProvider) {}

  create(dataItem: DataItem) {
    return this.provider.createDataItem(dataItem);
  }
}

class DataProvider {
  createDataItem(dataItem: DataItem) {
    return backend.save(dataItem);
  }
}

After:

class DataService {
  async create(dataItem: DataItem) {
    return backend.save(dataItem);
  }
}

Two files collapsed into one. No loss of clarity. Massive gain in readability.

Favor Services Over Factories

Before:

const service = ServiceFactory.get('data');
service.create(dataItem);

After:

dataService.create(dataItem);

The factory added nothing but indirection.

Architect for AI Collaboration

Assume your pair programmer is an LLM. Flatten structures, slice state into domains, and make naming explicit.

Before (monolithic state):

interface ApplicationState {
  containers: List<Container>;
  dataItems: Map<ID, DataItem>;
  uiState: UIState;
  connection: ConnectionState;
  // ... dozens more
}

After (domain slices):

interface AppState {
  page: PageState;
  data: DataState;
  ui: UIState;
  sync: SyncState;
}

A model can now read and explain one slice without drowning in an 80-property blob.

Stay Aware of AI's Limits

As I wrote in my post on mental models and prompt engineering, LLMs are pattern-matchers, not reasoners. They inherit bias, they hallucinate, and they choke on hidden indirection. Don't anthropomorphize them, and don't expect them to reconstruct intent buried under five layers of Providers and Managers.

The 5-Minute Rule

If you can't explain what an abstraction does in 5 minutes to a new developer (or AI), it's too complex. Simplify or remove it.

Abstraction Isn't Dead, But the Defaults Have Changed

Abstraction isn't going away. It was never the enemy. The problem is that too much of it, stacked without discipline, turns into an obstacle rather than a tool. What I'm describing here isn't necessarily guidance only for the AI-assisted programming; it's simply a principle we should strive for regardless of whether we're coding alongside AI agents or not: clarity beats unnecessary indirection.

But in the AI era, the tradeoffs have become even sharper. Every abstraction has to earn its place.

Does it genuinely reduce cognitive load? Does it make the code more straightforward for humans, machines, and the test suite? Can you explain its purpose in 5 minutes or less?

If the answer is no, then the abstraction is adding weight, not lifting it.

This case against abstraction isn't absolute. It's contextual. But the context has shifted. With or without AI, the best code is rarely the most abstract; it's the most direct.

A Practical Caching Playbook

Wed, 03 Sep 2025 00:00:00 GMT

If you've ever pushed a change to production and your browser stubbornly kept showing you the old version, you've experienced caching, probably not in a good way.

HTTP caching is one of those topics that can seem deceptively simple ("it just stores stuff locally"), but the details matter. Done right, it makes sites feel lightning-fast and reduces server load. Done wrong, it causes confusing bugs and outdated resources to linger.

This isn't a deep dive into every caching strategy, it's the quick, developer-focused overview I wish I had when I first started building for the web. At the end, you'll find resources for going deeper.

Why We Cache

Fetching resources over the network is slow and expensive, not just in terms of latency, but also in wasted bandwidth and server strain.

Caching lets us store a copy of a resource (HTML, CSS, JS, images, fonts, etc.) so that when it's requested again, the browser can serve it directly from local storage instead of hitting the network. This reduces load times, network traffic, and the chance that a user gets a partially loaded or broken page.

The process is simple in theory:

Browser requests a resource.
Browser checks its cache for a valid copy.
If it finds one, it serves it immediately.
If not, it fetches from the server and may store a copy for next time.

It's not the most flexible system, you have limited control over lifetimes, but it's built into every browser and requires minimal setup to get started.

How Browser Caching Works

Before diving into headers and strategies, it helps to understand the mechanics of how browsers actually decide whether to serve something from cache or go back to the network.

The Cache Decision Process

When a browser requests a resource, it doesn't just blindly fetch it. Instead, it follows a decision tree that looks roughly like this:

Is the resource in cache?
   ├─ No -> Fetch from network, store in cache
   └─ Yes -> Is the cached copy fresh?
       ├─ Yes -> Serve from cache
       └─ No -> Send conditional request to server
           ├─ 304 Not Modified -> Use cached copy, update freshness
           └─ 200 OK -> Replace cached copy with new version

This process explains why you sometimes see "304 Not Modified" in DevTools: the browser already had the file, it just needed the server to confirm it was still valid.

What Defines the Cache Key

It's also worth knowing that browsers don't cache purely by URL. The cache key includes several factors:

The URL itself – the primary identifier.
The HTTP method – GET requests are typically cacheable, while POST, PUT, and DELETE are not.
The Vary header – if present, it tells the cache to consider certain request headers (like Accept-Encoding or User-Agent) as part of the key.
Authentication state – private resources may be cached separately per user to avoid cross-user leaks.

Understanding this process makes the rest of the article easier to follow: headers like Cache-Control, ETag, and Last-Modified plug directly into this decision-making loop, shaping whether the browser trusts what it already has or goes back to the server.

The Key HTTP Response Headers

You'll usually configure caching at the response header level (the browser handles request headers for you). The main players:

Cache-Control, Defines how and for how long (in seconds, relative to the request time) the browser should cache a resource (e.g., max-age=8640000 for 100 days).
Expires, Sets a timestamp after which the resource is considered stale. Overridden by Cache-Control if both are present.
Last-Modified, Timestamp indicating when the resource last changed; used for conditional requests.
ETag, A unique identifier (often a hash) for a resource version. Any change to the file should generate a new ETag.

Headers like Cache-Control and Expires rely on time-based freshness. Last-Modified and ETag use validation, the browser asks the server if the cached copy is still valid, and the server replies with a 304 Not Modified if nothing has changed.

Example:

# Static assets with content hashing
Cache-Control: public, max-age=31536000, immutable

# HTML pages that reference changing assets
Cache-Control: no-cache

# API responses that are user-specific
Cache-Control: private, max-age=300

# Critical resources that must be fresh
Cache-Control: no-store

# CDN-optimized content
Cache-Control: public, max-age=3600, s-maxage=86400

A Closer Look at `Cache-Control`

If there's one header that defines how caching really behaves, it's Cache-Control. Think of it less as a single setting and more as a collection of knobs you can tune depending on what you're serving. The most common is max-age, which tells the browser how long a file should be treated as fresh. A script with Cache-Control: max-age=86400 will stay valid for a full day before the browser asks the server again.

Not all content should linger that long. For sensitive responses, banking APIs, for example, you'd go with no-store, which prevents caching altogether. no-cache is more subtle: it still allows the browser to keep a copy, but forces it to check with the server before reusing it. That makes it a good fit for HTML pages that often reference new versions of CSS or JavaScript bundles.

Some directives are about what happens after a file goes stale. With must-revalidate, the browser has no choice but to confirm with the server before showing the file again. By contrast, stale-while-revalidate gives you a performance trick: the browser can serve the old file instantly while quietly fetching the fresh one in the background. Combined with long cache times, this creates the illusion of zero-delay updates.

Another important distinction is whether content is meant for just one user or many. Marking a resource as private keeps it in the user's browser only, while public allows intermediaries like CDNs to cache and share it across requests. This small distinction often decides whether your API response leaks into a shared cache or stays safely scoped to the user.

Finally, if you're serving versioned or hashed files that will never change, you can declare them immutable. This tells the browser it doesn't even need to check back with the server once a file is cached, making it perfect for assets like fonts, image sprites, or JavaScript bundles. The directive really shines when paired with modern bundlers such as webpack, Vite, or Rollup, which generate files with unique content hashes in their names (app.3f29c1.js). Each new build produces new filenames, so the browser sees them as brand-new resources. The result is the best of both worlds: current files are cached aggressively and served instantly on repeat visits, while new builds automatically invalidate the old ones.

Performance Implications

Each directive affects performance differently:

immutable: Fastest - no network requests for cached resources
max-age: Fast for fresh content, validation for stale
no-cache: Always requires validation request
no-store: Always requires full request

In practice, most setups end up with a mix: long-lived, immutable caching for static assets; private or no-store for anything user-specific; and short-lived or no-cache for HTML documents. The art lies in combining these directives so that your users always get a fast response without getting stuck on outdated code.

Avoiding Stale Responses

Sometimes you don't want the browser to serve a cached file, especially right after deploying a new CSS or JavaScript bundle. In development, the quick fix is to disable caching entirely in your browser's DevTools, but in production you need a more deliberate strategy.

One common approach is cache busting. Instead of reusing the same filename, you append a unique query string or, more reliably, let a bundler like webpack, Vite, or Rollup generate hashed filenames automatically (app.3f29c1.js). Each new build produces new filenames, so the browser treats them as brand-new resources, sidestepping the risk of serving outdated code. Another option is to adjust cache lifetimes directly: keep shorter max-age values for assets that change often, while giving rarely updated resources a much longer lifetime.

In my own projects, I've leaned heavily on bundler-driven content hashing. It's simple, automatic, and works much like ETags at the HTTP level: whenever the content changes, the identifier changes with it. The result is that caches stay fresh without you having to invalidate anything manually.

Debugging and Testing Caching

One of the hardest parts of caching is that problems are often invisible, the browser quietly serves you an old file and you don't realize it until something feels "off." The fastest way to confirm what's happening is to open your browser's DevTools and check the Network tab. There, the Size column will reveal whether a file came directly from the server or was pulled from disk or memory cache. You can also toggle the "Disable cache" option to force every request to hit the server, which is invaluable during debugging.

On the command line, tools like curl or httpie are equally helpful. Running curl -I https://example.com/app.js shows only the response headers, letting you verify whether Cache-Control, Expires, or ETag are set the way you expect. Adding an If-None-Match or If-Modified-Since header to the request simulates what the browser does during validation, and you'll know caching is working if the server replies with a simple 304 Not Modified.

For a higher-level view, performance audits such as Lighthouse or PageSpeed Insights can flag assets that aren't cached efficiently. And if you're troubleshooting right after a deployment, don't forget the basics: a normal refresh may still serve cached files, while a hard refresh forces the browser to fetch fresh copies. It's a quick sanity check that often clears up "phantom bugs" before you dive deeper.

Debugging rule of thumb: when a bug seems to linger mysteriously, always suspect the cache before the code.

How I Cache in Practice

Over time I've settled on a few simple patterns that work well in most front-end projects:

For static assets like images or fonts, I give them a long max-age and serve them under hashed filenames so they can sit safely in cache for months or even years.
For CSS and JavaScript bundles, I rely on hashed filenames too. That lets me use long cache durations while still getting instant invalidation whenever I deploy a new build.
For HTML, I usually keep caching short, or set no-cache, since it often points to fresh bundles that need to be pulled in right away.

And when something strange shows up in production? My first step is almost always to clear the cache and try again, and you'd be surprised how many "mystery bugs" vanish as soon as stale files are out of the way.

Caching is one of the easiest performance wins in web development, but it's also one of the easiest ways to create subtle bugs. The trick is to be intentional: decide what can stay cached, for how long, and how updates will reach users. Get that balance right, and caching becomes an ally rather than a source of frustration. After all, the fastest network request is the one you never have to make.

Useful Resources

Thinking Clearly in Code: What Works for Me

Wed, 03 Sep 2025 00:00:00 GMT

TL;DR

As a developer, I've found that staying creative isn't just for designers or product folks, it's core to solving problems, navigating ambiguity, and keeping my head clear. These four strategies help me stay mentally fresh, especially during heavy cognitive days.

Creative thinking isn't about artsy vibes; it's about problem-solving under pressure, thinking in systems, and finding new angles when the obvious path doesn't cut it. Software engineering requires this kind of creativity every day. Whether I'm designing an API, debugging a race condition, or simplifying messy legacy code, the ability to think clearly and inventively is essential.

Here's how I protect that part of my brain from burnout.

1. I Stay (Relentlessly) Organized

When my workspace is cluttered, my brain usually is too. Starting and ending the day with a clean desk helps me feel less scattered, especially if I've been deep in the weeds with unfamiliar code or switching contexts between projects.

But it's not just about physical stuff. I usually try to plan out my week so I'm not constantly surprised by deadlines. I block off time for deep work when I can. Even just writing out three priorities each morning clears space in my head for higher-order thinking. When I feel organized, I can actually think, not just react.

2. I Move My Body When I Feel Mentally Jammed

There's a direct link between physical movement and creative insight, especially when you're stuck. If I've been staring at the same function for 30 minutes, it's a signal to get up. A walk, stretching, or even standing up to refill my water bottle can trigger clarity.

This isn't fluff. Research shows regular movement improves both divergent thinking (multiple ideas) and convergent thinking (narrowing to one solution). Both are critical in engineering, especially in design discussions or debugging sessions.

So yeah, sometimes "step away from the keyboard" is the best dev tip I can give myself.

3. I Let Myself Experiment (Even in Code)

Not every idea has to be "the one." Sometimes the path to a good solution is paved with deliberately bad ideas. I give myself space to sketch, spike, and ask dumb questions out loud, especially when exploring unfamiliar territory. Many times, I reach the answer by tinkering, stumbling into a working approach, and then tossing out the messy first draft to rebuild from scratch with a cleaner, more intentional design. Starting fresh helps me strip away accidental complexity and keep only the parts that actually move the solution forward.

Collaboration helps here. Pairing with a teammate, rubber ducking, or just throwing a bad idea into the Slack void can surface better ones. If I'm stuck, I often reframe the problem: What's the simplest version? Could this be two smaller problems? What if I broke this contract entirely, and what would the consequences be?

Sometimes, getting creative is just about zooming out or flipping the problem upside-down.

4. I Write Down Every Idea - Even the Weird Ones

I used to trust myself to remember clever ideas that popped into my head mid-task. I don't anymore. Now I jot down everything, in Notion, sticky notes, wherever.

Half of them go nowhere, but the act of capturing them helps me stay open and curious. Sometimes two scraps connect days later into something solid. Other times, writing it down clears mental space so I can focus on what's in front of me.

This habit helps me capture creative “drift” while staying grounded in what I'm working on.

Reflection = Creativity Boost

Every week or so, I do a mini-retro: What made me feel creative? What drained me? When did I feel most "in flow"? This gives me data about what conditions support my best thinking and how I can replicate them. This can feel like an extra task you'd rather skip, but the long-term payoff is enormous. I’ve even set up a Notion template that automatically appears at the end of the week, making it harder to ignore and easier to build the habit.

In software, creative insight doesn't always look like an eureka moment. Sometimes it's a small refactor that saves hours of debugging later. Sometimes it's knowing when not to ship a feature. But either way, keeping your creative brain limber is a fundamental skill worth cultivating.

Final Thoughts

Remote work, fragmented teams, and too many Slack/Teams channels can make creative thinking feel rare. But I've found it's something I can nurture with small, deliberate habits. Staying organized, moving around, experimenting freely, and capturing ideas as they come, that's what keeps me sharp.

What do you do when your thinking starts to feel stale?

How are you writing a commit message?

Wed, 03 Sep 2025 00:00:00 GMT

I'll write a little bit about a topic that is not related to code, seemingly not that important, but it is quite practical in daily programming. How to write git commit message properly?

No way of writing is right or wrong; however, if each person in a project has its own style of a commit message, then when we look at the commit history, does it look good? Not to mention when we need to search and review commits in the commit of the previous months through commit messages without any rules.

Commits that are non-consistent in a message format or don't follow any rules can be a problem because of many reasons:

Reading the commit message without knowing what the exact purpose of the commit was.
When we need to summarize changes in source code after a period of development (e.g. production release)
Choosing suitable new version, v1.0.0, v1.0.1, v1.1.0 or v2.0.0 etc.
Trying to search through commits via regex

<figcaption>Obligatory xkcd</figcaption>

Some teams decide to implement a kind of closed rules to solve some of the issues caused by fragmented code commit message styles. Why closed you ask? That is because those are local to your project. For example, in my team, we had a convention to prefix commit messages and git branches with the ticket number.

So are there any rules that are common to all of us and can be shared across many projects? Enter...

Conventional Commits

Conventional Commits are a set of commit message writing rules that create rules that are easy to read for both machines and humans. The machines can make use of these rules, for example, in tools for automatic versioning.

This set of rules corresponds to SemVer (Semantic Version) by the way it describes features, bug fixes, code refactors, or breaking changes made in commit messages. Currently, at the time of this writing, this set of rules Conventional Commits is in version 1.0.0-beta.4, and there may be future additions. You can refer to the implementation of conventional commits in some open projects on Github, some of the bigger ones are Electron, IstanbulJs, Yargs and Karma which, if I've understood correctly, actually laid foundations to semantic commits.

The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer]

Where:

The type and description are required by commit message, and all others are optional.
type: keyword to classify if the commit was a feature, bugfix, refactor... Followed by the :.
scope: is used to categorize commits, but answers the question: what does this commit refactor | fix? It should be enclosed in parentheses immediately after type, e.g. feat(authentication):, fix(parser):.
description: a short description of what was modified in the commit.
body: is a longer and more detailed description, necessary when the description cannot fit one line:

$ git commit -m "feat: allow the provided config object to extend other configs

BREAKING CHANGE: `extends` key in the config file is now used for extending other config files"

footer: some extra information such as the ID of the pull request, contributors, issue number(s)...

Some examples for a short commit message as follows:

# ex1: 
git commit -m "feat: implement AVOD content reels"

# ex2: 
git commit -am "fix: routing issue on the main page"

# ex3 with scope: 
git commit -m "fix(player): fix player initialization"

Semantic Versioning

Conventional Commit matches SemVer through type in the commit message. Automated versioning tooling also relies on it to decide the new version for source code. With the following convention:

fix: a commit of the (bug)fix type is equal to PATCH in the SemVer.
feat: a commit of type feature is equal to MINOR in the SemVer.
Also, the keyword BREAKING CHANGE in the body section of the commit message will imply that this commit has a modification that makes the code no longer compatible with the previous version. Like changing the response structure of an API, the handle response part of the previous structure will of course no longer be accurate, and now we need to create an entirely new version by bumping MAJOR SemVer version.

Some common type uses include:

feat: a new feature for the user, not a new feature for a build script
fix: bug fix for the user, not a fix to a build scripts
refactor: refactoring production code
chore: updating gulp tasks etc.; no production code change
docs: changes to documentation
style: formatting, missing semicolons, etc.; no code change
perf: code improved in terms of processing performance
vendor: update version for dependencies, packages.
test: adding missing tests, refactoring tests; no production code change

While these are the most common types that you're going to see in the wild, nothing is stopping you from creating your own types of commits.

Another bonus advantage from using semantic commits is that you can derive a sense of effort from git logs. For example, given below is a year worth of git commits in karma (master branch):

$ cd /tmp/karma
$ git log --pretty=oneline --no-merges --since 2017/01/01 --until 2017/12/31 | cut -d " " -f 2 |\
cut -d "(" -f 1 | cut -d ":" -f 1 | sort -r | uniq -c | sort -nr -k1
     39 chore
     28 fix
     23 feat
     15 docs
      6 test
      2 Try
      1 refactor

Using the scope annotation we could further slice and dice this data into questions like which component has the most number of bug fixes?.

Summary

Commit messages must have a prefix of a type (noun form) such as feat, fix and so on, Immediately followed by scoped (if any), a colon and space.

git commit -am "test: add missing tests for promo reels"

feat This type is required to use when adding a feature
fix This type is required to use when fixing a bug
If there is scope, the scope must be a noun that describes the area of the code change and must be placed immediately after type. Eg, feat(authentication). (Examples?)

git commit -am "refactor(auth): improve refresh token logic"

The description must be a short description of the changes in the commit and must be after the type with or without a scope.
A long commit can have the body right after the description, providing context for the changes. There must be a blank line between description and body.
The footer can be placed immediately after the body, but there must be an empty line between the body and the footer. Footers should include extended information about commits such as related pull requests, reviewers, breaking changes. Each information on one line.
Other types than feat and fix can be used in the commit messages.
Committing breaking changes must be specified at the beginning of the body or footer with the capitalized BREAKING CHANGE keyword. Followed by a colon, space, and description. For example:

$ git commit -m "feat(OAuth): add scopes for OAuth apps  

BREAKING CHANGE: environment variables now take precedence over config files."

An exclamation mark ! can be added before the type/scope to get attention and emphasize that the commit contains breaking change.

So now, after the project is using Conventional Commits we have:

Human readable project history
measuring and classification of effort
way to use Semantic Release to automate versioning and automatically generate changelogs for the project with semantic-release plugins.
way to use Commit Lint to lint commit messages according to Conventional Commits.
and finding, filtering and analyzing the commit history is also more straightforward when you can use the regex or git tools to filter commits by type or scope (or both).

Some useful links

https://www.conventionalcommits.org/en/v1.0.0-beta.4/#specification https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit https://github.com/conventional-changelog/commitlint/tree/master/%40commitlint/config-conventional https://karma-runner.github.io/0.10/dev/git-commit-msg.html https://electronjs.org/docs/development/pull-requests#commit-message-guidelines https://chris.beams.io/posts/git-commit/#seven-rules https://codito.in/semantic-commits-for-git

Really nice Cover Photo by Yancy Min

Thanks for reading!

Building Collaborative Interfaces: Operational Transforms vs. CRDTs

Mon, 22 Apr 2024 00:00:00 GMT

"Can we make it work like Google Docs?"

It's a request that sounds simple until you try to build it.

Real-time collaboration is one of those features that feels like magic when it works. Two people typing into the same document, edits appearing seamlessly, no conflicts, no data loss. But under the hood, it's a carefully choreographed system of synchronization, merging, and conflict resolution.

As a senior engineer, I've come to see that real-time editing isn't just a UI challenge; it's an architectural one. Whether you're building a document editor, a collaborative whiteboard, or a multiplayer code environment, you eventually face a core decision: how do you model and reconcile concurrent changes to the same data?

Two major approaches have emerged to solve this: Operational Transforms (OT) and Conflict-free Replicated Data Types (CRDTs). Each has its philosophy, strengths, and trade-offs, and picking the right one isn't always obvious.

In this post, I'll walk through:

What OT and CRDTs are (in plain English)
How do they solve the problem of collaboration
Where each shines and where they fall short
How to choose the right one for your architecture

Whether you're building the next Notion or just curious how collaborative tech works under the hood, this post aims to give you a clear, practical foundation.

Why Collaborative Editing Is Harder Than It Looks

At a glance, real-time collaboration seems like a networking problem: sync edits between clients and you're good, right?

Not quite.

The real challenge lies in handling conflicting edits from multiple users, especially when those edits happen at the same time, in different places, or offline. Let's say two people insert text at the same position in a document. Whose change wins? In what order? And how do we ensure that everyone eventually sees the same result, without clobbering anyone's work?

Some of the core problems collaborative systems need to solve:

Concurrency: Multiple edits happening simultaneously on the same data
Ordering: Ensuring consistent operation ordering across clients
Conflict resolution: Resolving divergent versions without manual merges
Latency: Keeping edits fast and responsive, even over slow or flaky connections
Offline support: Handling edits made offline and merging them correctly later
Scalability: Syncing changes efficiently across many users and devices

In traditional single-user apps, you can trust that changes happen in a known order and context. In collaborative systems, you lose that guarantee; you now need to deal with partial views, out-of-order events, and race conditions between human intentions.

This is where OT and CRDTs come in. Both are designed to ensure eventual consistency, meaning that regardless of the edits made and their order, all users will end up with the same state. But they take radically different paths to get there.

Let's explore how each works and what that means for you as an engineer.

Operational Transforms: Old School, Still Useful

Operational Transforms (OT) is one of the earliest and most battle-tested approaches to real-time collaboration. If you've used Google Docs, you've likely seen it in action, without realizing it.

How It Works

At its core, OT is based on this idea:

When a user performs an operation (like inserting or deleting text), that operation is sent to a central server.
The server receives operations from all clients, determines their order, and transforms incoming operations to account for other concurrent operations.
The transformed operations are then broadcast back to all clients, ensuring that everyone consistently applies changes.

Imagine two users trying to insert a character at the same position. OT resolves this by shifting one operation forward (or backward) so the result makes sense for everyone.

This process of transforming operations against each other is the key. It allows each client to apply changes locally and immediately, while still converging to the same final state.

Strengths

Mature and Proven: OT has been used in production systems for decades.
Low-latency UX: Edits appear instantly (optimistic updates), with conflicts resolved on the backend.
Efficient: Operations are usually small, and the server controls ordering.

Weaknesses

Hard to Implement Correctly: Writing the transformation functions (e.g., for text, trees, etc.) is non-trivial and error-prone.
Server-Centric: OT relies on a central authority to maintain order. It's not ideal for offline-first or peer-to-peer apps.
Not Naturally Composable: Composing OTs for rich content (like lists inside tables inside documents) becomes complex.

Real-World Usage

Google Docs: Arguably the most famous use case
ShareDB: An open-source OT-based backend for JSON/document editing
Firepad: Collaborative code/text editor built on Firebase and OT

Example

Suppose we have this initial text:

"Hello"

User A inserts "X" at position 1 → insert(1, "X")
User B deletes character at position 2 → delete(2)

Initial:   "Hello"
User A:    insert(1, "X")  → "HXello"
User B:    delete(2)       → "Hllo"

Without transformation, applying both ops in the wrong order could break the text.

With OT, we transform each op against the other so both edits are preserved meaningfully.

CRDTs: Sync Later, Merge Automatically

While OT was designed for centralized collaboration, CRDTs (Conflict-free Replicated Data Types) were born from the needs of distributed and offline-capable systems. If OT is all about ordering and coordination, CRDTs take the opposite approach: let every device do what it wants, and merge later, automatically.

How CRDTs Work

CRDTs are special data structures that are mathematically designed to be:

Commutative (order doesn't matter)
Associative (grouping doesn't matter)
Idempotent (reapplying changes doesn't change the result)

This means you can:

Apply changes in any order
Synchronize without needing a central server
Merge state from any number of devices; even after long periods offline

There are two main types of CRDTs:

Operation-based CRDTs: Sync deltas (changes); smaller network load but require reliable delivery.
State-based CRDTs: Sync complete state periodically; simpler merge logic but heavier payloads.

Example: If two people both insert characters at the same spot, a CRDT structure ensures both are preserved and deterministically ordered.

Strengths

Perfect for Offline-First Apps: Clients can work independently and sync later.
No Central Server Required: Suitable for peer-to-peer and edge architectures.
Automatic Conflict Resolution: You don't need to write transform functions or deal with "merge hell."

Weaknesses

Heavier Resource Usage: May store tombstones, causal metadata, or complete histories.
Complex Data Structures: Lists, nested objects, and rich text require advanced CRDT variants.
Less Mature Ecosystem: Tooling is growing, but not as battle-tested as OT.

Real-World Usage

Automerge: JSON-like CRDT library for JavaScript
Yjs: Highly optimized CRDT framework, widely used in collaborative editors
Figma: Uses a hybrid model, with CRDT-like properties for real-time sync
Notion: Uses CRDT-based techniques for syncing changes offline

Example

Let's say the initial value is an empty list: []

User A inserts "A" at position 0 (offline)
User B inserts "B" at position 0 (offline)

Initial:   []

User A (offline):   insert(0, "A")  → ["A"]
User B (offline):   insert(0, "B")  → ["B"]

// When both clients sync:
CRDT merge:         → ["A", "B"]   // or ["B", "A"], based on internal IDs

Final (consistent): ["A", "B"]     // same across all devices

When both sync:

The CRDT merges these operations into a consistent order (e.g., [A, B] or [B, A]) based on causal metadata
No data is lost, and both clients reach the same result: no manual conflict resolution required

Choosing the Right Model: OT or CRDT?

There's no universal winner between Operational Transforms and CRDTs, it all comes down to your product's needs, constraints, and future roadmap.

Below is a practical guide to help you choose the right approach.

Decision Criteria

1. Do users need to collaborate offline?

Yes → CRDTs are the better fit. They allow users to work offline and merge changes later without conflicts.
No (always-online app) → OT may be simpler to implement and more efficient.

2. Is your system centralized or peer-to-peer?

Centralized: OT is optimized for client-server topologies.
Decentralized or P2P: CRDTs are built for this, with no need for a central authority.

3. Is document fidelity critical (e.g., rich text, layout precision)?

OT works well for linear content (like text), but complex structures require a lot of custom work.
CRDTs support nested and structured data (JSON, trees), but often need more memory and tuning.

4. How much control do you have over the client environment?

Full control (e.g., internal tool or company-wide app): OT might be fine, since you can enforce coordination rules.
Public, multi-device, or mobile-heavy apps: CRDTs handle edge cases like clock skew, unreliable networks, and user churn more gracefully.

5. Is data merge correctness more important than sync speed?

For instant collaboration with low conflict rates: OT can be faster.
For resilience and correctness even under messy conditions: CRDTs shine.

⚠️ Important: these models aren't mutually exclusive. Some modern tools (like Notion or Figma) use hybrid approaches: OT for performance-critical paths, CRDTs for background sync and recovery.

Closing Thoughts: Choose the Right Tool for the Right Collaboration

Real-time collaboration is no longer a niche feature, it's a baseline expectation in modern productivity tools. But building it is anything but trivial.

Both Operational Transforms and Conflict-free Replicated Data Types offer robust solutions to the problem of concurrent edits, but they approach it from fundamentally different angles:

OT shines in environments where coordination is possible and performance is critical.
CRDTs excel when flexibility, offline support, and distributed trust are essential.

As engineers, our job isn't to chase elegance or novelty, it's to ship systems that work for real people in the real world. Understanding the trade-offs between OT and CRDTs can help you build collaborative experiences that don't just sync; they scale, they recover, and they feel right.

Bottom line is: You don't just choose a sync algorithm; you choose a collaboration philosophy:

OT is about control and coordination.
CRDTs are about trust and eventual harmony.

Either way, it's not just about the data structure; it's about how your users interact, when they connect, and what they expect.

Coding in the Age of AI

Mon, 22 Apr 2024 00:00:00 GMT

When ChatGPT first started making waves, I was skeptical. I figured it was another shiny tech fad that might be fun to play with, but wouldn't really stick in my day-to-day work. Fast forward, and now I can't imagine programming without some form of AI in my toolkit.

I'm not saying AI has replaced my skills, far from it. But it has reshaped how I approach problems, especially the boring, repetitive, or purely mechanical parts of development. Here's what that looks like from my side of the keyboard.

Before AI

If you've been coding long enough, you know the "classic" dev cycle:

Plan: Define the problem, sketch out solutions, argue with teammates on naming conventions.
Code: Write everything from scratch, guided by docs and hard-earned experience.
Debug: Stare at logs, sprinkle console.log like holy water, and pray.
Test: Scaffold unit tests by hand, often repeating the same setup boilerplate for every new module.
Optimize: Refactor with a mix of pride and dread (dread optional - unless you don't have tests).
Document: Write docs, knowing half the team won't read them until they're in trouble.

This worked, but it was slow. The bottlenecks were everywhere: manual lookups, repetitive boilerplate, and long debugging cycles.

After AI

Now, the flow feels different.

Coding feels lighter because AI can autocomplete, scaffold, or suggest idiomatic patterns on the fly.
Debugging is faster because I can paste an error trace and get a plausible diagnosis without trawling Stack Overflow for an hour.
Testing is quicker. Last week, Cursor wrote around 90% of my test stubs in seconds. I still shaped the edge cases and assertions, but the grunt work was already done.
Documentation isn't a chore, because tools can generate a first draft as I go, which I then tweak.
Learning curves are shorter when I can have an AI walk me through a new framework like a patient senior dev.

I mostly use ChatGPT, Cursor, and occasionally Claude Code. The tool matters less than the workflow you wrap around it.

How I Actually Use AI in My Work

Coding

I treat AI like a pair programmer who's great at boilerplate but still needs oversight. It's amazing for repetitive patterns such as CRUD endpoints, config files, and unit test scaffolds. I keep the final say, but letting AI start the draft saves me mental energy for the tricky parts.

Debugging

Instead of reading a wall of stack trace alone, I throw it into AI and say, "Explain what's happening and why this might be failing." It's not always perfect (especially for legacy projects with a lot of spaghetti code), but it often points me toward the right layer of the problem faster than blind searching.

Documentation

I've stopped writing all the docs from scratch. I'll have AI generate inline comments, API usage examples, or even a draft README from the code itself. Then I refine. The end result is better because I'm starting from something structured instead of a blank page.

Security is Still on Me

If there's one big "don't," it's handing over sensitive code or credentials. I keep anything proprietary out of prompts unless I'm working with a trusted, privacy-conscious tool. When I do need to share something delicate, I anonymize it or reduce it to the smallest reproducible snippet.

Some rules I follow:

Stick to reputable AI providers and disable code sharing for proprietary projects.
Strip or obfuscate sensitive data before pasting code in GPT.
Keep the AI software updated to avoid vulnerabilities

Advice If You're Just Starting

Start small: use AI for a specific part of your workflow, not everything at once.
Stay in the loop: always read and understand generated code before shipping. If something seems off, then make sure you know what and why LLM is suggesting to do something.
Ask, don't just paste: the more context you give AI, the better it performs.
Keep learning: use AI to understand solutions, not just implement them.
Treat it like a teammate: collaborate, don't outsource thinking.
Watch out for prompt fixation. LLMs are great, but they’re not infallible. Don’t get stuck repeating prompts that used to work. Mix up your phrasing, try new structures, and stay reflective instead of falling into autopilot

The Bottom Line

AI hasn't made me obsolete. It's made me faster, more adaptable, and frankly, more willing to experiment. I still need to understand the problems I'm solving, but I can spend more of my time on architecture, design, and creative solutions instead of boilerplate and tedious debugging.

In a way, AI hasn't changed what programming is for me. It's still about problem-solving. It's just changed the ratio of my time between "figuring stuff out" and "getting stuff done."

Improving your (Web) Dev Foo

Mon, 22 Apr 2024 00:00:00 GMT

I've been writing this since the last year, and in the end, I wasn't sure if I should publish it as this is mostly just a rant. Hopefully, some of you might find something interesting here as I wrote up some of the stuff I've learned and I'm doing in practice to keep writing effective and clean code.

Editor/IDE

If you are starting learning about web development, you can't go wrong, pick any code editor and code on.

Currently, for web development, there are many choices when you come to choosing the editor for your work. I use Webstorm/Xcode combo for work and VS Code/Vim for my stuff. From my experience, my suggestion would be that beginner devs start learning with a simple editor without many plugins, such as VS Code, Notepad ++ or Sublime Text, typing out all those keywords and language methods by hand helps a lot with memorizing/learning all that stuff. Once you feel comfortable with a language you're writing your code with, you can switch to full-blown IDE like Webstorm or plugins enhanced VS Code.

Linters & Formatters

TLDR: Use Eslint and Prettier

When your code base gets bigger, it's also more challenging to keep an eye on all those lines, and syntax errors problems creep in. By highlighting problematic code, undeclared variables, or missing imports, your productivity can be increased a lot and is going to save a lot of time and many nerves as well.

Using Eslint from a very start would also help a lot with learning Js, as it will force you to build healthy habits and write clean code. Over the years, I've tailored my version of the eslint rules based on eslint-config-airbnb, but lately, I've been looking into Wes Bos's eslint config and would probably give it a go in a some of my future projects.

Beside Eslint I'm using Prettier for code formatting, combined with husky and lint-staged for automating linting/formatting as precommit hooks.

The optimal directory structure

Dan Abramov's solution

I have mixed feelings about this topic. The only thing that I'm sure of is that there is no right solution. Every application is different in some way or another, and each project has its own distinct needs. How we structure our applications should change based on the needs of the project, just like the technologies we choose.

Do not try to optimize the project structure from the beginning of the project, but keep in mind that changing the project structure later in the project can be a problem in VCS because of history rewriting.

That being said, don't overthink it. Pick a folder structure that works for your application. If you’re spending a massive amount of time organizing and reorganizing components, containers, styles, reducers, sagas, you’re doing it wrong.

File naming

Rant incoming

Regarding file naming, one rule that I find immensely useful is this: name your file the same as the thing you’re exporting from that file. I can't stress enough how angry I feel when I have hundreds on index.js files in a poorly structured project, and finding some chunk of logic takes so much time, which feels wasted...

It staggers me that some people are happy to work like this.

Even if your IDE is clever and puts the directory in the tab name for non-unique filenames, you still have a bunch of redundancy there, and will run out of tab room sooner, and you still can’t type the filename to open it. Having said that, I understand that there is the reasoning behind this — It’s a definite trade-off. Shorter import statements vs. file names that match exports.

Not a worthy trade-off, in my opinion.

In my case, for the last two or three years, I'm mostly using CRA's project structure, with a few modifications, like adding a redux/ or sagas/ dir for state management logic and moving all jsx/tsx files to components/.

Debugging

Just console.log anywhere where you think there is a code "smell."

Writing about debugging can be a post on its own, yet there is a lot of already excellent posts and courses on Js debugging so I'll keep it short.

Many devs would say that using debugger looks more professional, but the console.log is something I'm using the most for a quick debugging. I'm lately working on the apps for Smart TVs and streaming devices, and those are not really debugger friendly, so logging data in console or going through device logs in telnet is sometimes the only way to debug. That aside, you should learn how to use the debugger, as it can save you with more complex bugs.

The simplest way to debug, at least in terms of tooling, is by reading the code you wrote. After that, use the console.logs, and if even that doesn't pinpoint the problem, switch to the debugger and good luck.

Documentation

Don't write a comment just for the sake of it. Write comments only for stuff that needs explanation.

We all (hopefully) know how important proper documentation and reference material is to a successful software project. Without good docs, a particular library may be next to impossible to use. Without a reference to how different components and methods work in isolation, let alone examples of how all the different pieces of a project fit together with each other, we are left to interpret the original intention of the author merely by reading the source code, or if we are lucky, reaching for StackOverflow and googling random error messages. If this is an in-house or small project, you are probably entirely screwed (been there).

This is especially important if you are working with several other fellow devs on the project; think about what the other member of the team is going to think about that hack you wrote when he doesn't know why is that needed. By keeping knowledge of how the code works and why is there many hacks in it or intentionally making code more complicated than it needs to be, you are just making lives of the everyone working on the same project more harder. And if you are doing this for the sole purpose of assuring your job security, you are just a censored.

For documenting my projects, I've been using JSDoc syntax. JSDoc is a standardized way of writing comments in your code to describe functions, classes, methods, and variables in your codebase. The idea is that we describe how our code works with a few special keywords and formatting conventions, and later we can use a parser to run through all of our commented code and generate beautiful, readable documentation based on the comments we write.

Here’s a short example of how's it looking like in practice:

/**
 * @desc Represents a book.
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

Some of this stuff can be replaced with Typescript types, but even with that, for more complex functions, it's helpful if we have a good explanation of what it is doing and why do we need it to do that.

Also, every and one hack in your code should be documented, believe me, future you are going to be thankful for that.

And for the end, if you already haven't, please read Clean-Code by Robert C. Martin. Writing clean and readable code is a skill on its own.

Learn Javascript

But seriously

Jumping on a Js framework or using a library to solve problems you have because you're not familiar with the core language is going to bite you soon enough. But do not despair, most of us have been there on some level, Js documentation is enormous and, unless you have an excellent memory, there is no way to memorize even a quarter of this stuff. But leveraging Pareto principle (also known as the 80/20 rule) would be in many cases just enough. Learn how is this working, all possible operations you can do with objects and arrays, that in Js everything is an object, scope rules, async ops, prototypes (you'll rarely use these, but it's essential to understand how inheritance in Js works) and coercion scenarios (so you can laugh at people making stupid mistakes by adding numbers to strings or arrays to arrays and then creating posts on Reddit flaming Js).

There is truth in saying that if you know Javascript good, then all frameworks and tools based on it are going to be much easier to learn. In the end, those are all just Js under the hood.

I can also recommend reading You Don't Know JS book series if you want to dive deep into Js core mechanisms. (I'm rereading it for the 2nd time).

Use the latest standards

Keep up with times

It can be challenging to keep up with all the things going on in the web development world, especially since the JavaScript language itself has been changing a lot over the last several years. In 2015, TC39, the committee responsible for drafting the ECMAScript specifications decided to move to a yearly model for defining new standards, where new features would be added as they were approved, rather than drafting complete planned out specs that would only be finalized when all features were ready. As a result, we have ES6 - ES10 specifications which have changed the language a lot, and in a better way. Each of these specifications includes a set of new features/improvements integrated into Javascript, nullifying the need for cumbersome libraries or tools so that you can work with Js and not pull your hair out.

If you want to get a quick overview of the features being considered for future releases, the best place to look is the TC39 proposals repo on Github. Proposals go through a 4 stage process, where stage 1 can best be understood as a cool “idea,” and stage 4 is “confirmed for the next ECMAScript release.” There is a lot of cool stuff coming with ES10 :)

If you’re interested in keeping up with new proposals but want somebody to walk you through them, I recommend subscribing to Axel Rauschmayer’s 2ality blog. But if you are more of a social interaction person, probably the easiest way to keep up with language evolution is to follow the people who are shaping and teaching the new language features: @TC39, Sebastian Markbåge, Mathias Bynens, Daniel Ehrenberg, Tierney Cyren, Axel Rauschmayer and probably a lot of other people I forgot.

Babel has implemented almost all of the higher stage proposals on the TC39 list, and you can try them out in the Babel REPL or by setting up a small project that loads in Babel with the appropriate plugins installed. Also, ff you aren’t familiar with ES6 yet, Babel has a excellent summary of its most essential features.

Typescript

Types good, boilerplate code bad

JavaScript is a loosely typed language, also known as a dynamically typed language, which means that it is flexible and does type checking on run-time rather than compile time. This means you can create a variable that starts as string type, but then change it to a number type, etc. For many people that have started programming in C or Java, this is horrifying (ergo coercion memes on Reddit), as those languages are pretty strict with types and require a full definition of data type or interface for a constant. Anyway, there’s a lot to love about static types: static types can be beneficial to help document functions, clarify usage, and reduce cognitive overhead. But, IMO, there’s a lot to love about dynamic types as well.

So, there comes Typescript. Typescript is Javascript, with an extra layer that adds static typing tools and capabilities to your Javascript code. As you’re developing an application, you will be writing Typescript code, which then gets compiled to plain JavaScript for the browser to understand. It can fix some of the issues dynamically typed languages have, a big plus is if you use one of the TS supported editors (VS Code, Atom, Webstorm) which can provide the excellent dev experience and boost your productivity. That aside, I hate a boilerplate code that comes with TS. A few TS projects I've been working with have at least 30-40% more lines of code just because of TS types, interfaces and enums. Errors can be cryptic sometimes, and debugging type issues can get on a nerve real quick. Merged types and some advanced type definitions can be tiring to read and understand sometimes.

There is a excellent article by Eric Elliott about Typescript's bad and good sides if you want to read more. Still, my overall opinion of TS is positive, just because whenever I go back to read the code, I can (almost always!) understand immediately and thoroughly what each type of variable is, what this function returns, whether this array has been changed throughout the program, etc. That's a lot of saved time and minimized the number of redundant operations to check the type and structure of the data.

Code testing, integration, and delivery

Give a developer a tedious task, and they'll find a way to automate it

Probably most of us here are familiar with tools as Webpack, Gulp, Grunt, lint-staged. Even Prettier and Eslint are a kind of automation tool. The less time we spend on menial or repeating tasks, the more time we have to focus on the actual problems.

Few developers get excited over the idea of writing tests for their code. Especially when there is a pressure to finish new features as fast as possible, writing test code that doesn’t directly contribute to the progress of the project can be annoying. When the project is small and you can test a few available features manually this might be fine, but once the project starts to grow manual testing is time-consuming and horribly inefficient.

Investing in testing upfront is one of the best investments you can make on your project. It is what allows you to write a feature, not touch it for weeks, come back, see it is passing all its tests, and have a level of confidence that everything is good in the world.

I've been using mostly Jest for my tests, but I've heard good things about Riteway. Testing React components have gotten more difficult since the introduction of the hooks, Enzyme is having a hard time so I'm not sure if I can recommend it anymore, react-testing-library might be a better choice for now.

Continuous integration is the software development practice of frequently integrating changes to a shared code repository. For every integration, automatic formatting and testing should be done. This gives the developers a quick feedback cycle for determining potential conflicts in commits while also allowing to frequently merge new updates to an application.

Continuous delivery works in conjunction with CI to take the tested and built application that results from the CI process and deploy (or deliver) it to the intended infrastructure. With CD, teams can push new code to production every day or even hourly and get quick feedback on what users care about.

A lot can be told about how to write tests and how to configure CI/CD pipeline but that would be a whole post on its own. There is no golden rule for how to write perfect tests but making sure that you at least write them and are trying to get ~80% coverage with a combination of unit, integration, and e2e tests should lead to clean and confident code.

Summary

I always struggle with summaries (same thing with prefaces). For me, it's usually hard to start writing a post, after that, I can go on and on, same with deciding how to end it :smile: I still feel like I haven't wrote enough about all topics mentioned, so feel free to comment if you have any questions.

Bear in mind that this is a half rant and half commentary to myself, after several years working with Js. There’s a whole class of internet comments that can be summarised as “I disagree, and that makes me ANGRY, here's a downvote”, which is a pity, because when two reasonable people disagree, there’s very often something interesting going on.

Thanks for reading!

Photo by Adi Goldstein on Unsplash

Making New Languages Click with LLMs

Mon, 22 Apr 2024 00:00:00 GMT

When I jump into a new language or framework, there's always that awkward period where I know what I want to do, but I don't yet know the way to do it. The docs help. Searching helps. But lately, I've found AI, specifically large language models, to be a surprisingly effective shortcut for getting up to speed.

That's been especially true recently as I've been learning Rust from scratch and re-learning Ruby after years away. In both cases, AI has helped me bridge the gap between knowing the outcome I want and understanding the idiomatic way to get there.

I'm not talking about letting AI write whole features for me and calling it a day. I use it like I'd use an experienced coworker: to explain unfamiliar syntax, walk me through tricky logic, or point out patterns I wouldn't have spotted. Here's how that looks in practice.

Prime It Like a Person

The most significant shift for me was realizing you can't treat AI just like a search box. It works better when you talk to it like it's a person with no memory of your project, because, spoiler, it is like that.

I start by giving it a role ("You're a Rust mentor helping me understand lifetime annotations in this function..."), set some rules, and provide the snippet or context I'm working with. The more specific I am, the better it answers. This is basically the "prompt library" habit—keeping go-to instructions that get me 80% of the way there for common questions.

For example:

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
    if x.len() > y.len() { x } else { y }
}

// My prompt to AI
"You’re a Rust mentor. Explain exactly why we need `'a` here
and how the compiler would complain if I removed it."

That way, I get an answer that goes straight to the nuance instead of a generic "this is a function" lecture.

I wrote about the mental models behind prompting and some of the common traps developers (and humans) fall into, and how to avoid them.

Use It to Decode Syntax Quickly

When I hit syntax sugar I don't recognize, I paste in the snippet and ask for a breakdown. I don't just want what it does, I want the "why" behind the choice.

For example:

def create_user(name:, email:, admin: false)
  { name: name, email: email, admin: admin }
end

create_user(name: "Alice", email: "alice@example.com")

If I weren't used to Ruby's keyword arguments, I'd feed just this snippet to AI and say: "Walk me through what's happening here and why admin has a default value."

The key is to focus on small, concrete chunks of code. If I throw in a 200-line file, the explanation gets vague. But if I isolate a pattern and ask for a line-by-line walk-through, I actually learn something I can reuse.

Pinpoint Where I'm Stuck in the Logic

Sometimes I understand most of the code, but one function call or return type throws me off. This is where I frame my prompt like I'm talking to a colleague: "I get it up to here, but then I'm lost, can you tell me what's happening next?"

By declaring what I do know, I make it easier for the model to skip the obvious and focus on the missing piece. That's saved me from drowning in over-explained basics.

Ask for a Refactor, Not a Rewrite

I'll sometimes ask AI to refactor a snippet, especially if I suspect it's inefficient or violating a language-specific convention. For example, removing an await from a for loop in Javascript, without breaking the logic.

I treat these as learning moments. I compare its suggestion with my own approach, figure out why it's better (or worse), and adjust. This way, I'm not blindly adopting AI output.

Generate Examples to Learn From

If I'm brand new to a language, I might have AI generate a function from a detailed description I give it. Then I dissect the result, asking follow-up questions about why it chose certain patterns, or whether there's a more idiomatic way.

This isn't about having AI "do the work." It's about creating a tangible example I can explore, question, and improve. Done right, it's like having an interactive coding textbook.

For Example:

"Write a Rust function that takes a list of words and returns only those longer than five letters, in alphabetical order."

AI output:

fn filter_words(words: Vec<&str>) -> Vec<&str> {
    let mut filtered: Vec<&str> = words.into_iter()
        .filter(|w| w.len() > 5)
        .collect();
    filtered.sort();
    filtered
}

Then I dissect it: Why into_iter instead of iter? Could it be more idiomatic with method chaining? What happens if I use sort_unstable?

The Bottom Line

AI isn't my teacher, it's my accelerator. It's not replacing documentation, real code reviews, or the need to tinker on my own. But when I use it deliberately, it helps me move through the clumsy "getting familiar" phase much faster.

If you're learning a new language, try using AI the way you'd lean on a helpful peer: ask focused questions, give it the right context, and use its answers as a springboard for your own understanding.

Parkinson’s Law in Software Engineering

Mon, 22 Apr 2024 00:00:00 GMT

If you've ever finished a task at the very last minute, despite having more than enough time, you've already experienced Parkinson's Law. It's the idea that "work expands to fill the time available for its completion." Cyril Northcote Parkinson first described the concept in Economist in 1955, and it has since become a well-cited principle in productivity studies.

If you give yourself a week to do a task, you'll take a week. If you give yourself four months, you'll still find a way to make it last four months. And in software engineering, where deadlines, sprints, and priorities shift constantly, this principle shows up everywhere.

How I've Seen It Happen First-Hand

The API

At one company, we started working on an API feature that should have taken two or three weeks (at most). Straightforward stuff, wire up a couple of endpoints, add tests, ship it. Instead, it dragged on for nearly four months. Why? Every week we'd add "one more thing", debating naming conventions, attaching edge-case functionality, or rewriting parts to make it "future proof™." The work didn't get harder; we just let the available time invite more work into the room.

The Feature Flags

Another time, we were tasked with removing a batch of old feature flags. On paper, this was cleanup work. A day or two, maybe a week. But because there wasn't a sharp deadline, it ballooned. We delayed, dependencies shifted, and soon those flags were entangled with new features. What could have been a tidy sweep turned into a gnarly refactor. The longer we waited, the harder it got.

Flaky Tests

At one of my previous companies, flaky tests were a recurring pain point. Initially, they should've been quick to fix, a 30-minute job here, an hour there. But when they got left for "later", suddenly they piled up into a backlog that took a whole week just for categorization. It took months to fix them all and bring the CI back to a stable state. Parkinson's Law doesn't just stretch individual tasks, it compounds when you defer maintenance.

Why Engineers Fall Into the Trap

The more time we think we have, the more we delay starting. By the time the deadline finally feels real, we're scrambling to finish anyway. Sound familiar?

Procrastination Disguised as Preparation

Without pressure, it's easy to tell yourself you're "planning" or "polishing." I've spent afternoons renaming variables and rewriting the code to be more performant and nicer when the real fix was already done an hour earlier.

Overengineering by Default

When there's time, scope expands. A hotfix turns into a refactor. A CRUD API becomes a new framework. Sometimes we call it "doing it right", but often it's Parkinson's Law whispering in the background. This overlaps with the Law of Triviality, where teams spend disproportionate effort on small details while bigger issues wait.

Management Isn't Immune Either

It's not just engineers who fall prey to Parkinson's Law. Managers fall into the same trap when planing sprints, setting timelines, or scheduling meetings. The same rule applies: the more time and space you give, the more things tend to expand and drag out.

Sprints Expand to Fit

If you give a team a two-week sprint, the work will stretch to fill two weeks. Even tasks that could be done in three days get scheduled and discussed until they spill over.

Meetings

If the calendar says 1 hour, the meeting will last 1 hour. I've seen 10-minute discussions dragged out just because the slot was there.

Big Project Deadlines

Give a team a vague "end of quarter" target, and you'll see Parkinson's Law bloom into endless scope creep, extra reviews, and "one last tweak."

Turning Parkinson's Law to Your Advantage

The trick isn't fighting it, it's using it.

Time-boxing

At another company, I've seen how time-boxing can save a messy discovery call. A concise 25-minute agenda forces clarity that an open-ended meeting can never deliver. The same applies to coding: two hours for a spike means you actually spike instead of redesigning the system. Agile teams rely heavily on this principle, framing all work within sprints or fixed blocks (Atlassian on timeboxing).

Artificial Deadlines

When I know a task could balloon, I try to give myself an earlier "fake" deadline. For example, I'll aim to finish a feature by Wednesday, even if the sprint closes Friday. That gap is my buffer for polish, rather than panic.

Smaller Work Units

Breaking a large ticket into smaller ones makes Parkinson's Law work for you. Each unit has a tighter deadline, which keeps the scope from sprawling.

Hackathon Constraints

I've seen hackathons produce working prototypes in 48 hours that would have taken months in a normal sprint. Why? The constraints kill off overthinking. You don't have the luxury to debate naming conventions, you just ship.

The Trade-Offs

Of course, speed isn't always better. Some work needs breathing room. Designing a distributed architecture or building core SDK APIs can't be rushed without long-term pain. The key is knowing when Parkinson's Law is helping you focus, and when it's luring you into cutting corners.

Another common trap: new managers who read about Parkinson's Law sometimes take it too literally. They assume that if shorter deadlines make people more efficient, then unrealistic deadlines must make them even faster. In practice, this backfires. Instead of encouraging focus, it creates a culture of constant firefighting, technical debt, and burnout. Deadlines should constrain scope, not crush the team. The art is in balancing enough pressure to avoid bloat, without crossing into "death march" territory (Asana's guide).

Wrapping Up

Parkinson's Law isn't just a productivity idea, it's a pattern I've seen in every engineering role I've had. Whether it's a sprint's work stretching over multiple sprints, a cleanup task turning into a refactor, or a project ballooning because "we have time," the principle holds: work expands to fill the space you give it.

The good news? With the right constraints, time-boxing, artificial deadlines, smaller tasks, you can flip Parkinson's Law into an advantage. The next time you're estimating a feature or planning a sprint, ask yourself: how much time does this really deserve? You might find that less time gives you better results.

Add PostCSS to Create-React-App

Mon, 22 Apr 2024 00:00:00 GMT

Without ejecting!

A small introduction to PostCSS

Many of you are spending your time working with CSS, so I guess you are familiar with preprocessors such as Less, Sass, and Stylus. These tools are a vital part of the web development ecosystem nowadays, and I cannot imagine writing styles for a website without using features like nesting, variables, or mixins as it can be cumbersome, awkward and sometimes less intuitive.

But, there is a couple of problems with traditional preprocessors:

They don't follow CSS standards. You might say that each of the preprocessors has become a standard of its own. Regrettably, they don’t aim at being compatible with the W3C standards, which means that they cannot you cant use their features as polyfills for early testing of the newer W3C standards.
They are not extendable. Whichever preprocessor you choose, you are limited to the set of features that it provides. If you need anything on top of that, you’ll need to add it as a separate step in your build process. If you feel like writing your extension, you’re on your own. Good luck with that.

This is where PostCSS comes in.

In a nutshell, PostCSS does the same thing as LESS/SASS/SCSS... But enhance it with a few plugins, and it can do much more. PostCSS is much like Babel for JavaScript. It parses your CSS, using Javascript under the hood, turning it into the raw AST (abstract syntax tree) and then performs transformations to the CSS that today's browsers will understand and render. And a bonus is that JavaScript can transform our styles much more quickly than other processors.

Enough about PostCSS and let's focus on the purpose of this post. After some Googling, I've found out that for PostCss to work, you had to eject CRA to edit the underlying Webpack configuration, which deals with all the necessary loaders for different file types, which I've found as a bit of a drastic measure. In the end, after a bit of trial and error hacking together different solutions, I got it working. Here’s how!

You can find the final code here: https://github.com/Puritanic/CRA-feat-PostCSS.

Edit: It seems that my google foo isn't good as I thought it was. Here's an alternate method for extending CRA with PostCSS created by @jonathantneal

First, create a new React app:

create-react-app postcss-cra
cd postcss-cra

And install postcss-cli and a few basic plugins

yarn add --dev autoprefixer postcss-nested postcss-cli npm-run-all

Then, at the root of the project, you need to create a file called postcss.config.js and add this code:

module.exports = {
    plugins: [
        require('postcss-nested'),
        require('autoprefixer'),
    ],
};

Almost there! Now all that is left is to edit the scripts in package.json :


    "scripts": {
        "build:css": "postcss src/styles/main.css -o src/index.css",
        "watch:css": "postcss src/styles/main.css -o src/index.css -w",
        "start": "npm-run-all -p watch:css start-js",
        "start-js": "react-scripts start",
        "build-js": "react-scripts build",
        "build": "npm-run-all build:css build-js",
        "test": "react-scripts test --env=jsdom",
        "eject": "react-scripts eject"
        },

Create a styles folder inside src where our CSS will live:

mkdir src/styles
mv src/App.css src/styles/main.css

And to test postcss, let's modify default CRA styles a bit:

/* src/styles/main.css */
.App {
  text-align: center;

    &-logo {
        animation: App-logo-spin infinite 20s linear;
        height: 80px;
    }

    &-header {
        background-color: #222;
        height: 150px;
        padding: 20px;
        color: white;
    }

    &-title {
        font-size: 1.5em;
    }

    &-intro {
        font-size: large; 
    }
}
@keyframes App-logo-spin {
  from { transform: rotate(0deg); }
  to { transform: rotate(360deg); }
}

Don't forget to remove import './App.css';' from App.js, as we've moved that file to styles and renamed it to main.css.

Moment of truth! Now run: yarn run start. In the browser, you should see almost the same styles that CRA by default has. Now let's see output index.css file in src/:

.App {
    text-align: center;
    display: flex;
    flex-direction: column;
}

.App-logo {
        -webkit-animation: App-logo-spin infinite 20s linear;
                animation: App-logo-spin infinite 20s linear;
        height: 80px;
    }

.App-header {
        background-color: #222;
        height: 150px;
        padding: 20px;
        color: white;
    }

.App-title {
        font-size: 1.5em;
    }

.App-intro {
        font-size: large;
    }

@-webkit-keyframes App-logo-spin {
    from {
        -webkit-transform: rotate(0deg);
                transform: rotate(0deg);
    }
    to {
        -webkit-transform: rotate(360deg);
                transform: rotate(360deg);
    }
}

@keyframes App-logo-spin {
    from {
        -webkit-transform: rotate(0deg);
                transform: rotate(0deg);
    }
    to {
        -webkit-transform: rotate(360deg);
                transform: rotate(360deg);
    }
}

Voila! As you can see, our styles are automatically auto-vendor-prefixed for better support, and our nested code is transformed to code that browser can understand.

Now let's do something more advanced:

yarn add -D postcss-import postcss-preset-env

After that, let's add those new plugins to postcss.config.js:

module.exports = {
    plugins: [
        require('postcss-import'),
        require('postcss-preset-env')({
            stage: 1,
        }),
        require('postcss-nested'),
        require('autoprefixer'),
    ],
};

Now, create a test files inside styles folder:

touch src/styles/styles.css src/styles/styles1.css

Move everything from src/styles/main.css to styles.css and add this:

@import 'styles.css';
@import 'styles1.css';

Now, in src/styles/styles1.css add this weird mumbo-jumbo:

@custom-media --viewport-medium (width <= 50rem);
@custom-selector :--heading h1, h2, h3, h4, h5, h6;

:root {
    --fontSize: 1rem;
    --mainColor: #12345678;
    --secondaryColor: lab(32.5 38.5 -47.6 / 90%);
}

html {
    overflow: hidden auto;
}

@media (--viewport-medium) {
    body {
        color: var(--mainColor);
        font-family: system-ui;
        font-size: var(--fontSize);
        line-height: calc(var(--fontSize) * 1.5);
        overflow-wrap: break-word;
        padding-inline: calc(var(--fontSize) / 2 + 1px);
    }
}

:--heading {
    margin-block: 0;
}

.App-header:matches(header, .main) {
    background-image: image-set('./img/background.jpg' 1x, './img/background-2x.jpg' 2x);
    background-size: contain;
}

a {
    color: rebeccapurple;

    &:hover {
        color: color-mod(var(--secondaryColor) b(15%) a(75%));
    }
}

Now restart CRA server. Everything should work as intended, except for several (obligatory) cats showing in the header now :D

This is just a scratch on the surface, PostCSS have enormous power in its plugins, and have a great community around it. What's the best is that the most of PostCSS plugins are using stuff that will be used as native CSS syntax in future, so your code is future-proof. In the end, I'm enjoying using it, and that's what matters, and I hope that you will too. Thanks for reading!

Some resources: Official PostCSS Github Repo and Page PostCSS-preset-env playground List of awesome PostCSS plugins

I've read... A Mathematician's Lament

Mon, 22 Apr 2024 00:00:00 GMT

"If you want to build a boat, don't order people to gather wood and assign tasks and work, but instead teach people to long for the boundless immensity of the sea."

A Mathematician's Lament is more of an extended essay than a book - one man's problems with mathematics education without a viable solution. While I agree with him that the current state of mathematics in schools and universities is a travesty, the kind of "solution" he recommends is not the real solution. We all know what most of us thought about the math (and many other fields) in ES and HS, and leaving it all to the student is not an excellent solution.

"Mathematics is the art of explanation. If you deny students the opportunity to engage in this activity - to pose their own problems, to make their own conjectures and discoveries, to be wrong, to be creatively frustrated, to have an inspiration, and to cobble together their own explanations and proofs - you deny them mathematics itself."

I think he argues that mathematics education gets tripped up in unnecessary formalism and syntax before conceptually interesting problems are tackled. The whole thing is defended with the ridiculous "you might need this someday" pragmatism that children will instantly tune out - is a sound one. It would be great if every elementary school teacher were the kind of engaged leader capable of putting their students to work on an exciting geometry or abstract algebra problem and wandering around not to give answers but to provide the occasional hint. But, unfortunately, I don't see how this will provide anyone with well-rounded mathematics education.

Don't get me wrong! I liked the premise of his essay. I would love that my professors had just a pinch of Lockhart's teaching spirit; it would make studying math much enjoyable. But, while I can see how it would make learning math so much more fun, it isn't practical. I think it could be accomplished in a small setting, but let's face it, the world doesn't allow for exploration. You have to master what they want you to master, troubling as that may be.

I've read... The Pragmatic Programmer

Mon, 22 Apr 2024 00:00:00 GMT

Truly a classic. It's definitely a must-read book for programmers and even people managing programmers. Initially released in 1999, The Pragmatic Programmer is a book about becoming a Pragmatic Programmer - programmer that's a true professional in their craft. And, even though it was published twenty years ago, it's fascinating to see the struggles we still face day in and day out discussed even then.

When I first started reading this book, I've expected a lot of technical details and lessons, which is probably one of the reasons why I've been avoiding this book so far. I mean, it's twenty years old, and in today's pace of technology, technical details do not stay up to date very long. But instead, this book concerns the most challenging parts of the programmer's career: writing scalable and maintainable software and scaling themselves as professionals.

There are code snippets, but the authors are aware of the code and techniques getting out of date in a matter of years, so the book is not focusing on them too much.

In general, there are not many surprises in what the book's authors are trying to deliver. Any programmer who cares about their craft, has no fear of change, and already has a few years of experience will already know many themes explored in this book. In my opinion, most programmers are aware of the guidelines this book is preaching, but they are also quick on finding excuses to ignore them.

The Pragmatic Programmer centers on how to use software to solve problems effectively and how to grow as the developer pragmatically; not just how to be a good programmer, but also how to solve the complex issues that surround coding, such as:

Writing clean code through DRY (Don't repeat yourself) and YAGNI (You aren't gonna need it)
How to estimate the software delivery.
How to institute change when others are hesitant.
How to combat stagnancy as a developer.
How to make the software processes resilient and efficient through automation and testing.

The examples and explanations are not abstract or far-fetched but are somewhat real-world applications of things you could see in the industry (though some stuff is outdated).

Some of the significant points of the book that I'm going to cover are:

We should take responsibility for our code and decisions.
Do not leave broken windows unrepaired.
Think critically
Know your tools
Program and refactor deliberately
Use Version Control
Test your code
Automate all the things

Hunt and Thomas are stating that the last three things from the list above are the essence of the Pragmatic Starter Kit, and that should be the three legs that support every project.

Responsibility

When you have responsibility for something, you should prepare yourself to be held accountable. If you make mistakes and cannot fulfill those responsibilities, you have to make up for them and find a solution. Don't give excuses and play the finger-pointing game. When you make a mistake (to err is human) or an error in judgment, admit it honestly and try to offer alternatives. Don't blame all the problems on a vendor, a programming language, management, or your coworkers. Any of these may play a role, but it is up to you to provide solutions, not excuses.

Don't approach anyone to tell them that something couldn't be done before you are entirely sure that that's correct. Additionally, don't just say you can't do it, like it's the end of the story. Instead, provide options and explain what can be done to salvage the situation.

As the authors of the book say:

Try to flush out the lame excuses before voicing them aloud. Does your excuse sound reasonable or stupid? How's it going to sound to your boss? (...) Try to flush out the lame excuses before voicing them aloud. If you must, tell your cat first.

Broken windows

There is a story about research studying the effect of broken windows on urban areas in the book.

One broken window, left unrepaired for any substantial length of time, instills in the inhabitants of the building a sense of abandonment—a sense that the powers that be don't care about the building. So another window gets broken. People start littering. Graffiti appears. Serious structural damage begins. In a relatively short span of time, the building becomes damaged beyond the owner's desire to fix it, and the sense of abandonment becomes a reality.

We, programmers, have probably seen this in some codebases. We see some broken code and think it's okay to leave it. We'll just come back when there is not enough work and fix it. But, unfortunately, this is just the first step to degradation of code quality and serious tech debt. After one broken window, the others will start appearing more frequently, and this is usually the time when developers start looking for a new job, leaving a dumpster fire behind.

So, (please), don't leave "broken windows" (bad designs, wrong decisions, or poor code) unrepaired. Fix each one as soon as it is discovered. If there is insufficient time to fix it properly, create a ticket, fix the most offending issue if possible, comment out the code, or leave a screaming comment. Ultimately, you should take action to prevent further damage and show that you're on top of the situation.

Do not fall to the Bystander effect, hoping that other developers will fix the problems. Instead, take the initiative, and be a catalyst for change.

Think critically

You should think critically about what you read and hear. You need to ensure that your knowledge and opinions are unswayed by either vendor or media hype. Beware of the salesman who insists that their solution provides the only answer; it may or may not apply to you and your project, or they might be just trying to sell you the snake oil.

Try to ask and think with the following questions when you want to get to the bottom of something:

Ask the "Five Whys" - Ask a question, and get an answer. Then, dig deeper by asking another "why?" Then, repeat the question as long as it's reasonable to do. You might be able to get closer to a root cause this way.
Who does this benefit? - It may sound cynical, but following the money can be a helpful path to analyze.
What's the context? - Everything occurs in its context, which is why "one size fits all" solutions often don't work. Good questions to consider are "best for who?" What are the prerequisites, what are the consequences, short and long term?
When or Where would this work? - Under what circumstances? Don't stop with first-order thinking (what will happen next), but use second-order thinking: what will happen after that?
Why is this a problem? - Is there an underlying model? How does the underlying model work? Do you even have the same problem?

Know your tools

This could seem like simple advice, but we are surrounded by a wide range of tools in our daily jobs. I don't know the ins and outs for each one I'm using, for sure.

For example, a few days ago, I've learned about git add --patch functionality that allows us to stage only parts of the changed files.

While I'm not sure that it would be advisable to learn everything possible about tools we're using for development, learning about stuff that can make you productive is definitely something we should strive for. For example, pay attention to your daily flow and see what manual actions you are performing most often. Then look if those can be automated or improved somehow.

The book teaches us that it's essential to find the proper tools before starting the development. By essential tools, it's not just the IDE but also the programming language and services. The more you are versed with different technologies, the wider the picture you'll have.

So before blindly jumping into coding, take a step back. Understand why the problem or the feature at hand needs to be built in the first place. Next, find the right tools for the job and start coding.

Some of the authors' recommendations:

Use plain text for everything. Avoid using binary formats to keep knowledge (such as MS Word).
Learn some scripting language well to use it for text manipulation (Js, Ruby, Python).
Learn shell (awk, grep, etc.)
Have your dotfiles configured and backup them regularly

Program and refactor deliberately

In the face of ambiguity, refuse the temptation to guess.

Be wary of premature optimization. It's always a good idea to make sure an algorithm is a bottleneck before investing your precious time trying to improve it. The less code is there, the fewer chances for bugs to happen.

Always be aware of what you are doing - if you don't understand the background of the feature you're implementing, you may fall victim to false assumptions. Don't blindly copy/paste code you don't understand, and don't do shotgun programming or programming by coincidence, as the book's authors call it. For example, suppose you don't know why or how your program works. In that case, you'll probably end up in a situation where you don't understand why the code is failing, which would usually result in spending a significant amount of time chasing the piece of code until you (if) know how it was working in the first place.

A litmus test for the above - can you explain your code to a more junior programmer? If not, perhaps you are relying on coincidences.

As mentioned in the previous section, don't jump to coding right away. Instead, create a plan, even if it's just a to-do list written as comments in your editor or on a napkin. After that, prioritize your efforts by spending time first on the complex parts of the problem.

Don't be a slave to history, meaning that you should not let existing code dictate future code. All code can be replaced if it is no longer appropriate. Even within one program, don't let what you've already done constrain what you do next, be ready to refactor, but keep in mind that this decision may impact the project schedule. The assumption here is that the impact of doing refactor will be less than the cost of not making the change.

Martin Fowler defines refactoring as a:

Disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior.

The critical parts of this definition are that:

The activity is disciplined, not a free-for-all
External behavior does not change; this is not the time to add features

To guarantee that the external behavior hasn't changed, you need good (preferably) automated unit testing that validates the code's behavior.

Use Version Control

This advice sounds a bit outdated, but it's worth a mention. Today's software development landscape is very different from twenty years ago, at least when version control is considered. git is deeply entrenched in the development flow, and I, myself, can't imagine working on a project without version control.

Additionally, the book suggests using version control for everything we deem important, notes and documentation as an example.

My take on this is that besides the version control, you should also strive to keep your git history clean and searchable (by using semantic commits, for example) and utilize the VCS for automation whenever possible.

Test your code

Yet another common-sense advice. And still, one that's not utilized as much as it should be, in most cases. Testing was important twenty years ago, but today it's even more critical when we account for a growing number of programs that can quickly kill people in case of malfunction.

Book authors even suggest that the test code should be larger than the program source code and that we should treat the test code with the same care as any production code. Keep it decoupled, clean, and robust. Don't rely on unreliable things like the absolute position of pages in a GUI system, exact timestamps in a server log, or the exact wording of error messages. Testing for these sorts of things will result in fragile (flaky) tests.

The pragmatic programmer is ruthlessly testing their code. The time it takes to write test code is worth the effort, as it ends up being much cheaper in the long run, with a chance of producing a product with close to zero defects.

Automate all the things

Automation is the core principle of being a pragmatic programmer. You should find whatever manual task you've or someone on your team has been doing and automate them. Automation leaves less space for human error and drastically improves the processes.

Automation also plays nicely with the other two "legs" of the pragmatic starter kit, version control, and tests. You should automate your processes to run tests on VSC changes and, if stable enough, even deploy the code to production on demand.

The more stuff you automate, the more time you'll have to dedicate to the real problems. But (!), don't fall into the trap of automating something that's not really worth the effort.

Pragmatic Teams

"Great things in business are never done by one person. They're done by a team of people." <cite>-- Steve Jobs</cite>

Teams as a whole should not tolerate broken windows—those slight imperfections that no one fixes. Instead, the team must take responsibility for the quality of the product.

As a final note, the book says that we, as individuals, should take pride in our work and leave our mark on it. However, we still need to balance this out when working in teams to not become prejudiced in favor of our code and against our coworkers. You shouldn't jealously defend your code against intruders, and you should treat other people's code with respect. The Golden Rule ("Do unto others as you would have them do unto you") and a foundation of mutual respect among the developers are critical to make this work.

Anonymity can provide a breeding ground for sloppiness, mistakes, sloth, and bad code, especially on large projects. It becomes too easy to see yourself as just a cog in the wheel, producing lame excuses in endless status reports instead of good code.

While code must be owned, it doesn't have to be owned by an individual. In fact, Kent Beck's eXtreme Programming recommends collective ownership of code (but this also requires additional practices, such as pair programming, to guard against the dangers of anonymity).

In the end, what you want of your career as a pragmatic programmer is for other people to recognize your signature. They see the feature or program built by you and expect it to be solid, well-written, tested, and documented.

Conclusion

I suggest this book to everyone; it's an easy and interesting read, even though senior developers are less likely to learn something new from it. Also, this is just a quick and short(ish) overview of the book's content, I haven't covered everything I've learned from it, and there is a lot of stuff that's also worth reading about, such as Orthogonality, Design by Contract, debugging, and Tracer Bullets technique, and more.

Shellscripting

Mon, 22 Apr 2024 00:00:00 GMT

Variables and Shebang

Small intro to shell programming

The Shell is the standard interface to every Unix and Linux system; users and administrators alike have experience with the shell, and combining commands into scripts is a natural progression. However, this is just a tip of the iceberg.

I've spent some time lately learning about shell and writing scripts, and I've realized that the shell is actually a full programming language with variables and functions, and also more advanced structures such as arrays (including associative arrays) and being so directly linked to the kernel it has native IO primitives built into it's very syntax, as well as process and job control.

I've planned this as a series of a few posts, and I'll try to be concise and on the point.

So, what is shellscripting?

Shellscripting is writing a series of commands for the shell to execute. It can combine lengthy and repetitive sequences of commands into a single and simple script, which can be stored and executed anytime, which is great for automating tasks. This reduces the effort required by the end user.

Script's commands are being executed by the interpreter (shell), one by one, and everything you can type in the command line you can also put in the script.

Before running scripts, we need to set up permissions for execution with: chmod 755 script.sh

We can then run the script with ./script.sh via command line.

#! (shebang) specifies binary of the shell (interpreter) we want to execute the script, for example: #! /bin/bash, #! /bin/zsh or for the best portability #! /bin/sh (this will run system shell).

Note that the most of code in this series is tested only with bash and zsh shell, most sh scripts can be run by Bash without modification, but some stuff wont work.

#! /bin/sh
sleep 90

When we execute the script that contains #! what actually happens is that interpreter is executed and the path used to call the script is passed as an argument. To confirm that, let's say we have sleepy.sh script, then we can run the script with ./sleepy.sh &, where & is used (it seems) to return the PID of the script execution process, and then we can run ps -fp [PID] to see process info:

UID PID PPID C STIME TTY TIME CMD
505 65418 59985 0 7:09PM ttys000 0:00.01 /bin/zsh ./sleepy.sh

We can see here that ./sleepy.sh is passed to my /bin/zsh binary as an argument.

If a script doesn't contain #! commands are executed with default shell, but it's the best practice to be explicit as different shells have slightly varying syntax.

Also, we don't have to use only shells as interpreters for scripts. We can also use other binaries like python:

#! /usr/bin/python

print "This is a Python script"

chmod 755 hi.py
./hi.py
This is a Python script

Variables

Variables are storage locations that have a name, and you can think of them as name-value pairs. Syntax used to create a variable is: VARIABLE_NAME="Value". It's important to note that variable names are case sensitive, and that, by convention, variable names should be all in uppercase. Also make sure to not use spaces after and before = sign, when declaring a variable.

By default all variables are global, also they have to be defined before used. Variables can be defined in the functions (we'll talk about them eventually), but we cannot access them before a function is called.

function var(){
    FUNC_VAR=1
}
# FUNC_VAR is not defined at this point and this will not return anything
echo $FUNC_VAR
var # This is how we call a function in the shell
# FUNC_VAR is now available because the function has been called
echo $FUNC_VAR # Output: 1

Valid variable names can consist of letters, numbers, and underscores, except that number cannot be the first char in the name.

# Valid names
DARK_JEDI="Vader"
GR4Y_J3DI="Ahsoka"
Regular_Jedi="Obi-Wan"

# Invalid names
3DARK_LORDS="Vader Sidius Plagueis"
TWO-REBELS="Solo Leia"
ONE@SHIP="Ebon Hawk"

#! /bin/bash
MY_SHELL="zsh"
echo "I like the $MY_SHELL shell" # Output: I like the zsh shell

We can also enclose the variable name in curly braces:

MY_SHELL="zsh"
echo "I like the ${MY_SHELL} shell" # Output: I like the zsh shell

Curly braces syntax is optional unless you need to precede or follow up the variable with additional data, like so:

MY_SHELL="bash"
echo "I'm ${MY_SHELL}ing on my keyboard!" # Output: I'm bashing on my keyboard.

Without curly braces this wouldn't work as the interpreter will take that ing following the name variable as a part of the variable name.

Another best practice is to enclose variables in quotes, when working with them, to prevent some unexpected side effects.

We can also assign the output of the command to a variable:

SERVER_NAME=$(hostname)
echo "You are running this script on ${SERVER_NAME}"

Local variables

Local vars are created with local keyword, and only functions can have the local variables, so they can only be accessed within the function where they're declared.

function myFunc(){
    local LOCAL_VAR=" I'm locally scoped"
}

It's the best practice to use only local variables inside functions.

That's it for now, I'll write a bit about tests and loops in the next one. Thanks for reading, and if you have any question, just ask away!

Shellscripting: Conditional Execution

Mon, 22 Apr 2024 00:00:00 GMT

This is the second part of the series on Shellscripting. In case you've missed it, you can find the first part here.

Also, note that the most of the code is tested only with the bash and zsh shells, it may not work with other shells.

Conditional execution means that you can choose to execute code only if certain conditions are met. Without this capability, all you would be able to do is execute one command after another after another. The ability to test a variety of things about the state of the system, and of the environment variables of the process, means that a shell script can do far more powerful things that would otherwise be possible. In this post, we are going to explore test operators, if/then/else conditionals, and case statements.

`test` aka `[`

With tests we can check for example: if the file exists, if a number is greater than another, compare if strings are equal...

Syntax:

[ condition-to-test-for ]

Example:

[ -e /etc/passwd ]

As heading above says, another name for test is [. It is also a shell builtin (which means that the shell itself will interpret [ as test, even if your Unix environment is set up differently). When [ is called, it requires a ] around its arguments, but otherwise, it does the same work.

test  -e /etc/passwd
# as above so below
[ -e /etc/passwd ]

This tests if etc/passwd exists, and if it does this returns true - command exit status of 0. If it doesn't exist the command exits with the exit status of 1 (more on exit statuses in next post).

Gotcha: The spaces around the [ and ] symbols are required! For example: [-e /etc/passwd ] will not work; it is interpreted as test-e /etc/passwd ] which errors because ] doesn't have a beginning [. [ is actually a program, and just like ls and other programs, it must be surrounded by spaces. Moral of the story: Put spaces around all your operators.

Note: You can reverse the results of the test with !:

if [ ! -r “$1” ]; then echo "File $1 is not readable – skipping."; fi

As you can see test is a simple but powerful comparison utility. For full details, run man test on your system, but here are some usages and typical examples:

File test operators:

-d FILE #True if the file is a directory
-e FILE #True if the file exists
-f FILE #True if the file exists and it's regular file
-r FILE #True if the file is readable by you
-s FILE #True if the file exists and it's not empty
-w FILE #True if the file is writable by you
-x FILE #True if the file is executable by you

String test operators:

-z STRING #True if the string is empty
-n STRING #True if the string is not empty
STRING1 = STRING2 #True if the strings are equal
STRING1 != STRING2 #True if the strings are not equal

Arithmetic tests:

arg1 -eq arg2 #True if the arguments are equal
arg1 -ne arg2 #True if the arguments are not equal
arg1 -lt arg2 #True if the arg1 is less than arg2
arg1 -le arg2 #True if arg1 is less than or equal to arg2
arg1 -gt arg2 #True if arg1 is greater than arg2
arg1 -ge arg2 #True if arg1 is greater than or equal to arg2

`&&` and `||`

It is possible to combine tests, and/or chain multiple commands by using the && and || operators. These perform a Logical AND and Logical OR, respectively.

&& = AND mkdir /tmp/bak && cp test.txt /tmp/bak

The command that follows && will be executed if and only the previous command succeeds (aka exits with 0 exit status).
|| = OR cp test.txt /tmp/bak || cp test.txt /tmp

The || operator performs a Logical OR, so when it only matters that one of the conditions is met, but not which one, this is the feature to use.

#! /bin/bash
HOST="google.com"
ping -c 1 $HOST && echo "$HOST reachable."

IF/THEN

Almost every programming language has an if/then/else construct, and the shell is no exception. The syntax uses square brackets to perform a test, and the then and fi statements are required, acting just like the { and } curly brackets in C and some other languages.

Syntax:

if [ condition ]
then
    statements for when the condition is true
fi

Other than the line break after the then, all these line breaks are required or can be replaced with semicolons. To remind: the spaces around the [ and ] symbols are also required, so this can be reduced (pls don't) at best to: if [ condition ];then statements;fi

It is quite common to use the semicolon to put the then on the same line as the if.

Example:

MY_SHELL="zsh"

if [ "$MY_SHELL" = "zsh" ]
    then
        echo "You are the zsh shell user!"
fi

ELSE

It may be that you want to run the command if possible, but if it can’t be done, then continue execution of the script. One (simpler and the most common) way to do this would be to use ELSE statement:

if [ condition ]; then
    statements for when the condition is true
else
    statements for when the condition is false
fi

#!/bin/bash

# Check for likely causes of failure
if [ -r "$1" ]; then
    cat "$1"
else
    echo "Error: $1 is not a readable file."
fi

This snippet tries to cat the file passed to it as its first parameter ("$1" putting double quotes around it to allow for filenames including spaces) and spits out an error message if it failed to do so.

ELIF

elif is a construct that allows you to add conditions to the else part of an if statement. It is short for "else if" so that a long string of possible actions can be written more concisely. This makes it easier to write, easier to read, and most importantly, easier to debug.

#!/bin/bash 
OS=`uname -s`
if [ "$OS" = "FreeBSD" ]; then
    echo "This Is FreeBSD"
elif [ "$OS" = "CYGWIN_NT-5.1" ]; then
    echo "This is Cygwin"
elif [ "$OS" = "SunOS" ]; then
    echo "This is Solaris"
elif [ "$OS" = "Darwin" ]; then
    echo "This is Mac OSX"
elif [ "$OS" = "Linux" ]; then
    echo "This is Linux"
else
    echo "Failed to identify this OS"
fi

This is much, much more readable than the nested else code hell this could turn into.

`case` statement

case provides a much cleaner, easier-to-write, and far more readable alternative to the if/then/else construct, particularly when there are a lot of possible values to test for. With case, you list the values you want to identify and act upon, and then provide a block of code for each one. One common place for case statements use are system startup scripts. Syntax:

case "$VAR" in
    pattern_1)
        # Some commands here.
        ;; # Execution will stop when the double semicolon is reached 
    pattern_n)
        # Some commands here.
        ;;
esac

Example:

#!/bin/bash
OS=`uname -s`

case "$OS" in
    FreeBSD) echo "This is FreeBSD" ;;
    CYGWIN_NT-5.1) echo "This is Cygwin" ;;
    SunOS) echo "This is Solaris" ;;
    Darwin) echo "This is Mac OSX" ;;
    Linux) echo "This is Linux" ;;
    *) echo "Failed to identify this OS" ;;
esac

Although it looks like a special directive, the * is simply the most generic wildcard possible, as it will match absolutely any string. This also suggests that we are able to do more advanced pattern matching like RegEx, for example.

Note that the patterns are case sensitive.

A less well-known feature of the bash implementation of case is that you can end the statement with ;;& or ;& instead of only ;;. While ;; means that none of the other statements will be executed, if you end a statement with ;;& all subsequent cases will still be evaluated. If you end a statement with ;&, the case will be treated as having matched.

#!/bin/bash

read -p "Give me a word: " input
echo -en "That's "
case $input in
  *[[:digit:]]*) echo -en "numerical " ;;&
  *[[:lower:]]*) echo -en "lowercase " ;;&
  *[[:upper:]]*) echo -en "uppercase " ;;&
  *) echo "input." ;;
esac

$ ./case1.sh
Give me a word: Hello 123
That's numerical lowercase uppercase input.

This feature is specific to the bash shell; it is not a standard feature of the Bourne shell, so if you need to write a portable script, do not expect this to work. It will cause a syntax error message on other shells.

This post has covered the various ways of controlling conditional execution — from the simple if/then/else construct, through the different things that can be done with test, through to the more flexible case statement for matching against different sets of input.

I must admit that writing about shell programming seemed like two or three posts tops in the beginning, but there is a lot to be covered, and even this and previous posts are not even the half of everything that can be learned about topics I've written about. I really recommend Advanced Bash-Scripting Guide and Classic Shell Scripting if you want to learn shell programming in more depth. I'll write a bit about Positional parameters, exit codes and (hopefully) functions in the next one. Thanks for reading!

Shellscripting: Functions

Mon, 22 Apr 2024 00:00:00 GMT

This is part three of my post series about Shellscripting, you can check out previous posts here:

For functions we can say that they're shellscripts within shellscript.

One of the main reasons why we are using functions is to follow the DRY principle, which means that we should write a function once, and then we can use it many times. This can sometimes drastically reduce the script length, and also it's much easier to maintain as we have a single function to edit and troubleshoot.

Function:

Hides implementation details from the main script, simplifying the shell script’s main body of code
Can be replaced if the underlying detail it works with is changed
Can be tested over and over again as a small piece of a larger script, with changing input values to prove that the code is correct
Allows consistent reuse of code from within the script, or even between several shell scripts.

<figcaption> <a href="https://xkcd.com/1168/">Slightly relevant xkcd 😄</a></figcaption>

Exit statuses

Before we dive into functions it's essential to know that every command executed in shell returns an exit status in the range of 0 to 255. De facto status for success is 0, all others are codes for an error condition. This codes can be used in scripts for throwing and checking errors. Usually, we can find what various exit statuses mean by checking the documentation for that error code or look into the source code.

We can use $? to check the exit status of the previously executed command.

ls dir/
echo $?

If dir exists echo $? will return 0 status code, otherwise, it should return 2, the error code for directory not found.

We can explicitly define the return codes with exit command:

#! bin/bash
HOST="google.com"

ping -c 1 $HOST

if ["$?" -ne "0"]
then
    echo "$HOST unreachable"
    exit 1
fi
exit 0

Simply use the exit command in your script and follow it with the integer in the range of 0 to 255. If we do not specify the return code with the exit command, then the exit status of the previously executed command in the shellscript will be used as the exit status. This is also true if we do not include exit command at all.

Whenever the exit command is reached the shellscript will stop running.

All functions have an exit status. We can explicitly return status within the function with return keyword:

function myFunc() {
    return 1 # returning exit status code 1
}

Also, status can be returned implicitly with the exit status of the last command executed in the function.

Positional parameters

Positional parameters are the variables which we can use to specify arguments passed to the function via command line. For example, if we execute the script like this:

script.sh param1 param2 param3

Inside that script we can access all command line arguments like this:

$0: "script.sh" # $0 is always the name of the script
$1: "param1" # $1 is the first parameter,
$2: "param2" # $2 is the second
$3: "param3" # $3 is the third, and so on...

NOTE: You cannot change the values of these variables

A practical example:

# args.sh
#!/bin/bash
echo "I was called as $0"
echo "My first argument is: $1"
echo "My second argument is: $2"
echo "I was called with $# parameters."

$ ./args.sh one two
I was called as ./args.sh
My first argument is: one
My second argument is: two
I was called with 2 parameters.

We can use $# to check with how much parameters script was called, which is a good way to check if the user has executed the script with enough number of args, for example:

$ cat argCheck.sh
#!/bin/bash
if [ "$#" -eq "2" ]; then
    echo "The script was called with exactly two parameters. Let’s continue."
else
    echo "You provided $# parameters, but 2 are required."

We can use $@ variable when we want to loop through script parameters:

# This will loop through all parameter passed to the script when executed
for USER in "$@"; do
    passwd -l $USER # lock the account
done

Creating a function

Let's get back to the functions. It's important to note that function must be defined before it's called, it is conventional to define functions at the start of the file, although this is not strictly necessary. The block of code defined as a function can be declared in one of three different ways, depending on the exact shell in use. The standard Bourne shell syntax uses the function name followed immediately by a pair of parentheses () and curly brackets {} around the code itself:

# The most common way
myFunc() {
    # Code
    echo "Hello"
}
# function keyword is optional
# so this is also correct
function mySecondFunc () {
    # More code
    echo "World"
}

There is a third syntax, which is not accepted by the Bourne shell, although bash and ksh both accept it. Instead of following the function name by a pair of parentheses, the function name is preceded by the keyword function: function myFunc

As far as I've learned so far, the first one (without keyword function) is the most commonly used as it's accepted by all shells. The second syntax is also used frequently and by using the function keyword, it provides a more clear declaration that it is a function. Regarding the 3rd one, I couldn't find any information about it, except that it exists :|

Calling a function

We can call and execute the function by simply typing its name in the script (after it's been defined first):

function hello() {
    echo "Hello World!"
}

hello

function hello() {
    echo "Hello ${1}!"
}

hello World # Output: Hello World

Functions can also call other functions. Here we can see there that the hello function calls now function before it's declared, but that's okay as the now function gets read into the script before the hello function is called, so in the order of the execution it's defined before it's used.

function hello() {
    now
}
function now() {
    echo "$(date +%r)"
}

hello # Output: 02:15:36 PM

But, for example, something like this won't work:

function hello() {
    now
}
hello # hello is called before now is defined
function now() {
    echo "$(date +%r)"
}

Besides calling other functions, shell functions can also call themselves recursively. A simple example to demonstrate this is the mathematical factorial function.

$ cat factorial.sh 
#!/bin/bash

function factorial() {
    if [ "$1" -gt "1" ]; then 
        previous=`expr $1 - 1` 
        parent=`factorial $previous` 
        result=`expr $1 \* $parent` 
        echo $result
    else
        echo 1
    fi
}
factorial $1
$ ./factorial.sh 6 720

You should be very careful when working with recursive functions tho, especially if you are creating files in them, you could end up with more open files than allowed by the system.

Functions also have positional parameters, and $@ can also be used to retrieve the list of all passed arguments.

# $0 is the script itself, not the function name
function helloFunc(){
    echo "Hello ${1} ${2}!"
}
helloFunc Shell World
# Output: Hello Shell World!

Functions also have access to all global variables. But, as a reminder, it's the best practice to use only local variables inside the functions to avoid side effects, which can eventually cause bugs.

There is much more to be said about the functions in shellscript, so consider this post just as a small introduction to their usage in scripting. In the next post, I'll write a bit about Wildcards, Character Classes and about logging and debugging shellscript. Thanks for reading!

Thinking Clearly with LLMs: Mental Models and Cognitive Pitfalls in Prompt Engineering

Mon, 22 Apr 2024 00:00:00 GMT

Large Language Models feel intelligent in conversation, but their behavior is fundamentally alien to human cognition. They don't think like we do, reason like we do, or understand context like we do. Yet we keep trying to interact with them as if they were human collaborators.

This mismatch leads to fragile, confusing, and often overconfident prompt engineering. We write prompts that work sometimes, fail mysteriously, and leave us scratching our heads about what went wrong.

The solution isn't better prompt templates or more sophisticated techniques. It's thinking more clearly about what LLMs actually are and how they actually work.

This post will walk through mental models that accurately describe how LLMs behave in practice, cognitive pitfalls that distort our reasoning when writing prompts, and practical frameworks for building more reliable AI systems.

Whether you're building AI features into your products or just trying to understand these systems better, this guide will help you avoid the traps that lead to brittle, confusing, or overconfident prompt engineering.

LLMs Don't Think Like We Do

The fundamental problem is that we anthropomorphize LLMs. We treat them like they have intentions, understanding, or agency. But they don't.

An LLM is a statistical pattern matcher trained on vast amounts of text. It predicts the next token based on what came before, nothing more. Yet we keep trying to reason with it as if it were a human collaborator. This fundamental misunderstanding is what Emily Bender and colleagues called the "stochastic parrot" problem in their influential paper.

This mismatch creates fragile prompts that work in some contexts but fail in others, confusing interactions where the model seems to understand but then behaves unexpectedly, overconfidence in the model's capabilities, and inefficient development cycles spent debugging "unpredictable" behavior.

The solution is to develop accurate mental models of how LLMs actually work and to recognize the cognitive pitfalls that lead us astray.

Durable Mental Models for Working with LLMs

The Stochastic Parrot

Core insight: LLMs are sophisticated pattern matchers, not reasoning engines.

At their heart, LLMs predict the next token based on statistical patterns in their training data. They don't "understand" concepts in the way humans do, but they recognize patterns and continue them.

This means ambiguity is problematic because vague prompts can produce unpredictable results. Precision matters, with specific, well-structured prompts working better. Hallucination is inevitable, as models will confidently generate plausible but false information. And context is everything, as the model's behavior depends heavily on the immediate context.

The practical takeaway? Write prompts that are explicit, specific, and leave little room for interpretation. Don't assume the model will "figure out" what you mean.

The Simulator

Core insight: LLMs can simulate roles, workflows, or behaviors based on the context you provide.

When you write a prompt like "Act as a helpful assistant," the model doesn't become an assistant. It samples from patterns in its training data that match how helpful assistants tend to speak and behave. In effect, you're constructing a lightweight simulation that persists for the duration of the prompt.

This is powerful. Specifying a role like developer, analyst, or teacher can shift the model's tone, structure, and output format. Roles help set expectations and improve consistency, especially across multiple turns. However, if you mix conflicting roles or instructions, the simulation can break down or become incoherent.

The practical takeaway? Be intentional about the role you want the model to play. Specify the persona, goals, and constraints clearly.

The Conversational Mirror

Core insight: LLMs echo your tone, ambiguity, and structure.

The model's output quality and style directly reflects the quality and style of your input. If your prompt is vague, the response will be vague. If your prompt is precise, the response will be more precise.

This means input quality maps directly to output quality, following the classic "garbage in, garbage out" principle. The model adopts your communication style through tone matching. Structure matters, with well-structured prompts producing well-structured responses. And each interaction builds on the previous ones for iterative improvement.

The practical takeaway? Write prompts as if you're writing for a very smart but literal colleague. Be clear, specific, and well-structured.

The Prompt is the Program

Core insight: Prompting is declarative, dynamic programming with text as the universal interface.

Your prompt is the "code" that runs on the LLM. It defines the inputs, outputs, constraints, and behavior. Like any program, it needs to be well-structured, modular, and maintainable. This aligns with the broader shift toward what Andrej Karpathy called Software 2.0, where programs are defined not just by explicit logic, but by data, models, and context.

Complex prompts often create layered, role-specific micro-worlds, with each layer having its own role, goals, and constraints. The model navigates these layers to produce appropriate responses. This layering can create sophisticated behavior, but role conflicts can arise when different layers have conflicting goals.

Since most interaction with an LLM happens through text, the prompt acts like its user interface. And just like any UI, clarity, structure, and consistency go a long way. A clear, well-structured prompt makes the model easier to work with and more likely to respond reliably. When your prompts follow consistent patterns, you get more predictable outputs. Over time, you'll spot fedback loops, what works, what breaks, where ambiguity creeps in, and that helps you refine things. This is why modularity matters. Break complex prompts into smaller, reusable parts. Keep track of what you change and why, just like you would with code.

The practical takeaway? Treat prompt engineering like software engineering. Use version control, test the model, document your approach, and design your prompts with the same care you'd use for a user interface.

Cognitive Pitfalls in Prompt Engineering

I've found knowing about the Einstellung Effect and Type III Error, in particular, instrumental in LLM prompting. Knowing about these two biases can help you a lot with structuring your prompts correctly.

Type III error: Solving the Wrong Problem

The pitfall: Framing mistakes lead to elegant failures.

In statistical reasoning, most people are familiar with Type I errors (false positives) and Type II errors (false negatives). Less well known, but just as important in prompt engineering, is the Type III error: solving the wrong problem.

This happens when a prompt is well-crafted and followed precisely by the model, but the output is irrelevant or unhelpful because the underlying task was misunderstood. The model does exactly what it was asked to do, but the prompt was aimed at the wrong goal. The failure is not in the execution, but in the framing.

You might assume the model can reason when it is really just predicting. You might misread what the user needs, focus on the wrong aspect of the workflow, or design an elegant prompt that misses the point entirely. Sometimes, the entire interaction is shaped more by the capabilities of the LLM than by what the broader system or product actually requires.

To avoid this pitfall, start with the actual problem rather than jumping to an solution. Clarify the task intent before writing any prompts. Test your assumptions about the problem at hand and what the model can actually do. Before writing a single token, step back and define the problem clearly. Only then should you start designing the prompt.

Start with the problem. Then design the prompt. Not the other way around.

The Einstellung Effect: Prompt Fixation

The pitfall: Reuse bias leads to suboptimal prompts.

The Einstellung effect is a cognitive bias where a familiar solution blocks recognition of a better one. In the context of prompt engineering, this often appears when a previously successful prompt becomes a default, even when it no longer fits the task.

Common mistakes include reusing the same prompt structure for different problems, not experimenting with different approaches, getting stuck in familiar patterns, or ignoring evidence that suggests a different approach.

To avoid this pitfall, stay flexible and iterative. Experiment with different prompt structures. Question your assumptions regularly. And look for evidence that suggests different approaches might work better.

Prompt Overfitting

The pitfall: A prompt that works on one example might fail everywhere else.

Prompt overfitting happens when you design and test a prompt using only one or two inputs, then assume it will behave the same way in general. It feels like success, but it's often an illusion. The prompt may have worked because the input was easy, familiar, or unintentionally aligned with the model's defaults. Once the input shifts, longer content, edge cases, different tone, the output breaks down or drifts unpredictably.

This is especially risky when you're working with limited test data or optimizing prompts by trial and error on a small set of examples. You end up with something that looks robust, but actually performs well only in narrow conditions.

To avoid this, evaluate prompts across a wide range of realistic inputs. Include examples that vary in structure, tone, length, or ambiguity. Treat your prompt like a function, it should be predictable, consistent, and stable under real-world conditions, not just the happy path.

The Fluency Illusion

The pitfall: Coherent ≠ correct.

LLMs are excellent at producing coherent, plausible-sounding text. But coherence doesn't guarantee accuracy, especially for factual or logical tasks. This is what researchers call the "fluency illusion", where models generate convincing but incorrect information.

Common mistakes include trusting the model's confidence, not fact-checking important information, assuming coherence means correctness, or not verifying logical consistency.

To avoid this pitfall, always verify important factual claims. Check for logical consistency. Don't trust the model's confidence level. And use the model for what it's good at (generation) while verifying separately.

Anthropomorphic Drift

The pitfall: Attributing agency where there is none.

It's easy to start thinking of the LLM as having intentions, understanding, or agency. When it comes to LLMs and AI, it's a particularly dangerous cognitive trap because the outputs sound human, even though they result from statistical inference. This is a natural response to fluent language, but it leads to overtrusting the model's output or falsely assuming it has reasoning abilities. This anthropomorphic bias is well-documented in human-AI interaction research.

Common mistakes include thinking the model "understands" your intent, attributing reasoning to statistical pattern matching, trusting the model's "judgment," or treating the model like a human collaborator.

To avoid this pitfall, remember that the model is a statistical pattern matcher. Don't attribute understanding or agency. Verify important outputs independently. And keep the model's limitations in mind.

Prompting as Debugging

The pitfall: Not treating prompt engineering as an experimental, iterative process.

Prompt engineering is more like debugging than traditional programming. It requires hypothesizing, testing, and refining based on results. This iterative approach is essential for building reliable AI systems.

Common mistakes include expecting prompts to work perfectly on the first try, not iterating based on results, not isolating variables when testing, or giving up too quickly when things don't work.

To avoid this pitfall, treat prompting as iterative and experimental. Hypothesize, isolate, and refine systematically. Test one change at a time. And learn from failures and unexpected results.

Conclusion: Mental Clarity Beats Prompt Tinkering

The most important skill in working with LLMs isn't knowing the latest prompt techniques or having the most sophisticated templates. It's thinking clearly about what these systems actually are and how they actually work.

When you understand that LLMs are statistical pattern matchers, not reasoning engines, you write different prompts. When you recognize that coherence doesn't equal correctness, you build different systems. When you see prompting as declarative programming, you approach it with different tools and practices.

The clearer you think about LLMs, the more reliable your outcomes will be. Mental models help you reason about these systems. Prompts are interfaces, not dialogues. And the better you understand the cognitive pitfalls that distort your thinking, the more effectively you can avoid them.

The future of AI development isn't about writing better prompts; it's about thinking more clearly about what we're actually building and how these systems actually work.

NSFW: Use cases for Bitwise operators in Js

Mon, 22 Apr 2024 00:00:00 GMT

Bitwise operators in Javascript are mostly used for numerical conversions/computations, because sometimes they're much faster than their Math or parseInt equivalents. You can take a look at some benchmarks here.

It’s important to note, as pointed out by Mathias Bynens, that bitwise operations only work reliably on numbers that can be expressed as 32-bit sequences. Any numbers above 2147483647 or below -2147483648 will not work as you expect. This is usually acceptable though.

However, JavaScript numbers are always 64-bit binary floating-point values, following the international IEEE 754 standard. Thus the results of bitwise operators, though computed with 32-bit integer math, are stored in the floating-point form. That works because the range of 32-bit integers fits comfortably and precisely in a 64-bit float.

But the price you have to pay for that increase in speed is code readability. Since I've started coding several years ago, I've maybe used bitwise operators once or twice, because most work I don't have much to do with computation. Nevertheless, I've been interested in bitwise operators usage in real-world code for a long time, and I have a gist with collected snippets from all over the internet, just in case I need it sometimes 😄.

So, here are some excerpts from my collection:

`| 0` is an easy and fast way to convert anything to integer

( 3|0 ) === 3;                 // it does not change integers
( 3.3|0 ) === 3;               // it casts off the fractional part in fractionalal numbers
( 3.8|0 ) === 3;               // it does not round, but exactly casts off the fractional part
( -3.3|0 ) === -3;             // including negative fractional numbers
( -3.8|0 ) === -3;             // which have Math.floor(-3.3) == Math.floor(-3.8) == -4
( "3"|0 ) === 3;               // strings with numbers are typecast to integers
( "3.8"|0 ) === 3;             // during this the fractional part is cast off too
( "-3.8"|0 ) === -3;           // including negative fractional numbers
( NaN|0 ) === 0;               // NaN is typecast to 0
( Infinity|0 ) === 0;          // the typecast to 0 occurs with the Infinity
( -Infinity|0 ) === 0;         // and with -Infinity
( null|0 ) === 0;              // and with null,
( (void 0)|0 ) === 0;          // and with undefined
( []|0 ) === 0;                // and with an empty array
( [3]|0 ) === 3;               // but an array with one number is typecast to number
( [-3.8]|0 ) === -3;           // including the cast off of the fractional part
( [" -3.8 "]|0 ) === -3;       // including the typecast of strings to numbers
( [-3.8, 22]|0 ) === 0         // but an Array with several numbers is typecast to 0
( {}|0 ) === 0;                // an empty object is typecast to 0
( {'2':'3'}|0 ) === 0;         // or a not empty object
( (function(){})|0 ) === 0;    // an empty function is typecast to 0 too
( (function(){ return 3;})|0 ) === 0;

Replacements for `Math.floor()`

(~~n)                           
n|n
n&n

// Generate random RGB value:
var r = ~~(Math.random() * 255);

~~null;      // 0
~~undefined; // 0
~~0;         // 0
~~{};        // 0
~~[];        // 0
~~(1/0);     // 0
~~false;     // 0
~~true;      // 1
~~1.2543;    // 1
~~4.9;       // 4
~~(-2.999);  // -2

// An example
const n = Math.PI;   // 3.141592653589793

Math.floor(n);       // 3
parseInt(n, 10);     // 3
~~n; // 3 
n|n; // 3            // n|n and n&n always yield the same results as ~~n
n&n; // 3

It should be noted that of these last three alternatives, n|n appears to be the fastest.

~~'s flooring capabilities make it a better alternative to Math.floor if you know you’re dealing with positives — it’s faster and takes up fewer characters. It’s not quite as readable though.

Parsing hexadecimal value to get RGB color values

var hex = 'ffaadd';
var rgb = parseInt(hex, 16); // rgb value is 16755421 in decimal = 111111111010101011011101 in binary = total 24 bits


var red   = (rgb >> 16) & 0xFF; // returns 255
var green = (rgb >> 8) & 0xFF;  // returns 170
var blue  = rgb & 0xFF;         // returns 221  

// How is it working:

// There are two bitwise operations as named SHIFTING and AND operations.
// SHIFTING is an operation where the bits are shifted toward a given direction by adding 0 (zero) bit for vacated bit fields.
// AND is an operation that is the same as multiplying in Math. For instance, if the 9th bit of the given first bit-set is 0
// and 9th bit of the given second bit-set is 1, the new value will be 0 because of 0 x 1 = 0 in math.

// 0xFF (000000000000000011111111 in binary) - used for to evaluate only last 8 bits of a given another bit-set by performing bitwise AND (&) operation. 
// The count of bits is 24 and the first 16 bits of 0xFF value consist of zero (0) value. Rest of bit-set consists of one (1) value.
console.log("0xFF \t\t\t\t: ", 0xFF) 


// 111111111010101011011101 -> bits of rgb variable
// 000000000000000011111111 -> 255 after (rgb >> 16) shifting operation
// 000000000000000011111111 -> 255 complement (changes the first 16 bits and does nothing for the last 8 bits)
// 000000000000000011111111 -> result bits after performing bitwise & operation
console.log("Red - (rgb >> 16) & 0xFF \t: ", (rgb >> 16) & 0xFF) // used for to evaluate the first 8 bits

// 111111111010101011011101 -> bits of rgb variable
// 000000001111111110101010 -> 65450 -> 'ffaa'
// 000000000000000011111111 -> 255 complement (changes the first 16 bits and does nothing for the last 8 bits)
// 000000000000000010101010 -> result bits after performing bitwise & operation
// calculation -> 000000001111111110101010 & 000000000000000011111111 = 000000000000000010101010 = 170 in decimal = 'aa' in hex-decimal
console.log("Green - (rgb >> 8) & 0xFF \t: ", (rgb >> 8) & 0xFF) // used for to evaluate the middle 8 bits 

// 111111111010101011011101 -> 'ffaadd'
// 000000000000000011111111 -> 255 complement (changes the first 16 bits and does nothing for the last 8 bits)
// 000000000000000011011101 -> result bits after performing bitwise & operation 
// calculation -> 111111111010101011011101 & 000000000000000011111111 = 221 in decimal = 'dd' in hex-decimal
console.log("Blue - rgb & 0xFF \t\t: ", rgb & 0xFF) // // used for to evaluate the last 8 bits.

console.log("It means that `FFAADD` hex-decimal value specifies the same color with rgb(255, 170, 221)")

`^` bitwise XOR as a `I/O` toggler

// https://stackoverflow.com/a/22061240/7453363
function toggle(evt) {
  evt.target.IO ^= 1;                                    // Bitwise XOR as 1/0 toggler
  evt.target.textContent = evt.target.IO ? "ON" : "OFF"; // Unleash your ideas
}

Check if number is odd:

function isOdd(number) {
    return !!(number & 1);
}

isOdd(1); // true, 1 is odd

Check whether indexOf returned -1 or not

var foo = 'abc';
!~foo.indexOf('bar'); // true

Flip a boolean value

var foo = 1;
var bar = 0;

foo ^= 1 // 0
bar ^= 1 // 1

Bitwise operators in JavaScript introduce weird situations where (12 & 9) === 8 and (12 & 3) === 0, which looks totally out of the place if you don't understand at first look what's happening beneath (and the most of the people I know don't, me included).

The performance differences, even though they may seem compelling, are entirely negligible in most cases. You should only sacrifice readability for performance if you really need to squeeze out those precious microseconds, and if you do that please leave a comment explaining what is happening, who knows, maybe you'll need it someday 😄. The only other reason for using these bitwise tricks is to make your code look more complicated than it really is, which is probably a stupid reason. There are also edge cases to watch out for, so you can't just replace all your current Math.floor() calls with ~~. Things will likely fail.

References

Where would I use a bitwise operator in JavaScript?

Why I Care (a Lot) About Fast CI

Mon, 22 Apr 2024 00:00:00 GMT

I’ve never heard an engineer say, “I love our CI.”
Programming languages, editors, frameworks — sure. CI? Usually silence… or grumbling in Slack.

For me, the root cause is almost always the same: slow pipelines. And slow CI doesn’t just waste time, it actively changes how engineers work — usually for the worse.

How Slow CI Hurts Teams

I’ve been on projects where a single CI run takes 45+ minutes. The result? People batch up changes into huge feature branches so they “wait less often.” In reality, reviewers now have to sift through massive diffs, making code reviews harder, slower, and less effective.

Slow CI also kills continuous improvement. Spot a small cleanup opportunity? Rename a variable? Upgrade a dependency? You might think twice if it means an hour-long feedback loop. And when the little fixes stop happening, they pile up — leading to bigger, riskier refactors later.

Signs Your CI Is Too Slow

I’ve found these to be the big red flags:

Large, long-lived branches becoming the norm.
Engineers skipping full local test runs because “it takes too long.”
People only running the specific tests they touched, never the whole suite.

Don’t obsess over a magic number for “acceptable build time” — look at these patterns. If they’re happening, your CI speed is below the productivity threshold.

Treat CI Slowness Like a Bug

The biggest shift for me was treating slow CI like a production issue.
It has a cost: wasted engineer time, reduced quality, and growing tech debt. That cost can exceed the impact of some actual user-facing bugs.

If you’re serious about fixing it:

Make it a team goal — something measurable, like “All builds under 15 minutes.”
Dedicate time to CI maintenance — just like you do for refactoring or bug fixing.
Give everyone ownership — engineers should understand and influence what runs in the pipeline, not just “throw code over the wall” to some invisible process.

Show Your Tools Some Love

We’ll spend hours tweaking our editors or shell configs, but the CI pipeline is the shared tool that every engineer uses daily. It deserves the same level of care — maybe more.

A fast, well-maintained CI isn’t magic. But it will:

Shorten feedback loops.
Encourage smaller, safer changes.
Make continuous improvement a habit, not a luxury.

If you want to see how I approach speeding up CI in practice, stay tuned for my follow-up on pipeline tuning for Elixir projects. And if you’re curious about our approach to macOS CI, check out Continuous Integration for Small iOS/macOS Teams.

Darko Tasevski — Writing

A Case Against Abstraction

Yesterday's Cure, Today's Disease

Case Study: When the Russian Dolls Collapse

Abstraction Layer Explosion

Custom Frameworks on Top of Frameworks

State Bloat

Pattern Proliferation

When LLM Models Hit the Wall

Test Suite Complexity and Flakiness

Why the Tests Were a Crisis

Quantified Pain

When Abstraction Actually Works

Good Abstraction Examples

The Key Difference

Why Humans + AI Both Need Directness

Practical Solutions

Audit Abstractions Like Dependencies

Favor Services Over Factories

Architect for AI Collaboration

Stay Aware of AI's Limits

The 5-Minute Rule

Abstraction Isn't Dead, But the Defaults Have Changed

A Practical Caching Playbook

Why We Cache

How Browser Caching Works

The Cache Decision Process

What Defines the Cache Key

The Key HTTP Response Headers

A Closer Look at Cache-Control

Performance Implications

Avoiding Stale Responses

Debugging and Testing Caching

How I Cache in Practice

Useful Resources

Thinking Clearly in Code: What Works for Me

TL;DR

1. I Stay (Relentlessly) Organized

2. I Move My Body When I Feel Mentally Jammed

3. I Let Myself Experiment (Even in Code)

4. I Write Down Every Idea - Even the Weird Ones

Reflection = Creativity Boost

Final Thoughts

How are you writing a commit message?

Conventional Commits

Semantic Versioning

Summary

Some useful links

Building Collaborative Interfaces: Operational Transforms vs. CRDTs

Why Collaborative Editing Is Harder Than It Looks

Operational Transforms: Old School, Still Useful

How It Works

Strengths

Weaknesses

Real-World Usage

Example

CRDTs: Sync Later, Merge Automatically

How CRDTs Work

Strengths

Weaknesses

Real-World Usage

Example

Choosing the Right Model: OT or CRDT?

Decision Criteria

1. Do users need to collaborate offline?

2. Is your system centralized or peer-to-peer?

3. Is document fidelity critical (e.g., rich text, layout precision)?

4. How much control do you have over the client environment?

5. Is data merge correctness more important than sync speed?

Closing Thoughts: Choose the Right Tool for the Right Collaboration

Further Reading & Resources

Coding in the Age of AI

Before AI

After AI

How I Actually Use AI in My Work

Coding

Debugging

Documentation

Security is Still on Me

Advice If You're Just Starting

A Closer Look at `Cache-Control`

`test` aka `[`

`&&` and `||`

`case` statement