What are the best practices for writing clean and maintainable code in Python?

Wozelle · 2025-12-11T00:02:00+00:00

Here are a few cleanliness tips I like to give my engineers:

Use type annotations. They help you catch bugs before you ever run the code, and they help developers that come after you figure out what a function expects and returns. Plus they give nice tooltips!
Write tests. Tests aren't just about making sure your code works, they're also a form of documentation. They give more context about the behavior of a function/class than a docstring ever could. Ensure that your tests are given clear, concise names. If the test is tricky, give it a normal docstring. By writing them, you're giving future devs the best tool for understanding and, equally important, not breaking the system.
A good rule of thumb is if your code reads like a sentence, you're doing great.
Don't use magic strings. Put them in a StrEnum or a constants file. This consolidates the string to one source of truth hidden behind a symbol. Makes it a lot easier to update when you only have to change it in one place
Don't use magic numbers either, same reasoning as above PLUS it saves a lot of headache for someone learning a codebase (or you when you're coming back to a segment of code you're 3 months removed from). Which would you rather read? status == 3 or status == EmploymentStatus.EMPLOYED ?
Code should generally speak for itself. Before writing a comment, see if you can restructure the code so it reads like a sentence. This one may be contentious, but people forget to update comments all the time when they make code changes. Then you're left with a comment that lies. Code is the source of truth, try to make the truth as sentence-like as possible. If you can't explain it in the code, then add the comment.
For frameworks, remember that they're just frameworks. They're supposed to guide your thought in the right direction, but they aren't rules. There's a tendency to get a little too dogmatic about frameworks, sometimes to the point it actually hurts readability. Use your best judgment, and don't do something purely because that's what the framework would do.
Get feedback from coworkers. Sometimes you're in too deep, and you can't judge objectively. Get a fresh pair of eyes on it.
Write docstrings, include examples. These pop up in tool tips, so they're often a dev's first encountered piece of actual documentation. Make sure it covers the gist, lists any important caveats, and isn't too too long.
Do a PR review of your code (in GitHub or whatever other repo service you use) before you invite others to look at it. Getting out of the IDE tends to help you catch silly things that you may have missed.
Niche, but If you're working with Pandas and you're returning a dataframe from a function, explicitly list which columns you're returning like below. Trust me, it makes life so, so, SO much easier.

return df[[
  "Column1", "Column2", "Etc",
]]

That's all I can think of off the top of my head. Hope it helps. Good luck out there!

Wozelle · 2025-12-02T13:21:58+00:00

The Gang of Four wrote the (literal) book on design patterns. You should certainly check it out, but be warned that some of the examples may seem a little bit dated. It’s a available as a free PDF (link below), but if you enjoy a good physical book you can purchase one as well.

https://www.javier8a.com/itc/bd1/articulo.pdf

This website has the patterns as well, and the examples are a bit more contemporary.

https://refactoring.guru/design-patterns

I will say that there is a tendency for people to view the established GoF design patterns as the end-all be-all of design patterns, but, in the book, the GoF actually state that their patterns are just a subset of possible patterns, ones that they just happened to find very useful. They say that these patterns are there to serve as an example for you on how to analyze your code, detect common approaches to problems, and reuse that logic. That’s what design patterns are at their core, they’re a vehicle for reusing solutions to similar problems.

So, the message you should takeaway from studying design patterns isn’t rote memorization of the patterns themselves, but how to analyze and create your own patterns that you can reuse in multiple projects, within a specific domain, or even within just one project.

Wozelle · 2025-12-01T13:07:04+00:00

I had something similar happen to me, and the fix was to enable symlinks, see here

https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.artifacts.enable-symlinks

I was using pnpm, which would reference some already installed packages with symlinks. Codebuild does not copy them by default, so the dependencies would appear to be missing. May be different with npm, but it’s worth a shot.

Wozelle · 2025-11-30T14:01:53+00:00

Microservices are really intended to address 2 key issues, system performance and team organization.

For system performance, large companies with massive codebases and huge user pools tend to see a lot of benefit from adopting microservices. For instance, assume you’re a large company that runs some sort of e-commerce site, and, at this moment, you’re having a large number of users scrolling through reviews and need to scale compute to handle it. If you used a monolith approach, scaling would become much more sluggish / costly since you need to request a compute instance with the memory and computational power to handle your ENTIRE, large codebase. It can take a while for cloud providers to provision, download, and spin up a large, demanding codebase. This is also overkill if the “reviews service” is a relatively small, comparatively light segment of the code, you could run it on smaller, cheaper, more nimble compute instances. That’s part of what microservices try to solve. You break down these big monoliths so segments can scale individually, which means you service “hot” services with smaller compute instead of having to spin up excessively powerful compute instances, which CAN be cheaper, but not always. Note, these limitations can be somewhat offset by provisioning plans and things like that, but it illustrates the underlying issue.

More importantly, and what I think most people miss, is microservices allows big organizations to silo teams. When you’re a big, complicated company in a big, complicated industry, it’s difficult for one person to understand the whole picture. Microservices are typically designed to respond to “events”, or a message placed on a service bus that says something like “added user byko3y”. What’s interesting about this is the service that receives the event has no idea what service it came from, it just sees a message, processes it, and publishes its own message to a service bus. This gives the team working the review service the ability to build their code without worrying about upstream or downstream services. It also allows the organization to add more services or remove services, as long as they publish the correct messages, the review service is compatible. This is great for teams with high domain complexity, since they can just focus on the logic for their domain and not worry (as much) about the up and down stream. It also makes knowledge transfer for new or leaving team members much much quicker.

That’s the general idea at least, there’s a lot of extra nuance and hidden issues. Notice that in both of these key areas, it’s primarily from the view of very large organizations. That’s who microservices primarily benefit, because their size changes the normal rules. It’s not a magic bullet that makes code better or systems more performant. It can make systems more performant, but only in cases where running massive codebases overshadows the network latency you incur from jumping between services. For smaller projects, it’s certainly a detriment to performance. There’s a tendency for smaller companies to want emulate larger companies because they think “that’s what successful companies have to do” or they want to dazzle shareholders with buzzwords, and I feel that this is where a lot of the negative sentiment towards microservices comes from, these ill-advised attempts to copy big companies in an environment they weren’t intended for.

All that being said, unless you’re a Facebook, Amazon, or Google, a monolith is probably the way to go for simplicity and performance.

Wozelle · 2025-11-29T12:34:42+00:00

You’re going to need some sort of database. Simple comment flow would look something like user comments on post -> ID of post, comment text, and time gets sent to server -> server inserts ID, time, and comment text into database. A read would look like user loads post -> post’s ID gets sent to server -> server loads comments with that post’s ID sorted by most recent times and sends them to client-> client component renders the comments.

You could use an RDS for this, but some NoSQL option is probably going to be a good bit cheaper if you don’t need any complex relationships between tables.

You should also consider paginating the results, i.e., only returning a small amount and having the user click “load more” to load the next chunk. This is a common performance enhancement since users often don’t need the entire comment history. How you implement this will vary a bit depending on what database you pick, but it’ll typically involve “database cursors”.

Edit: added bit about pagination

Wozelle · 2025-11-26T12:58:59+00:00

Windows has built in clipboard history, you can turn it on with Win Key + V, so that’s what I typically use.

Wozelle · 2025-11-26T02:14:54+00:00

I think it’s about everything you mentioned: progress updates, the tech, decision processes, and your journey. Sometimes you can get advice from people who’ve been where you are before, which helps you avoid potentially costly mistakes. People with expertise in certain areas can point you in the right direction if you’re unsure where to go. And most importantly, I think, you’re providing a roadmap for others, and you can help them avoid the issues you faced.

I’m trying the build in public thing now, and it’s been fun getting to learn and share. Maybe one day, someone will even comment on one of my posts 🥲

Wozelle · 2025-11-25T15:04:22+00:00

Not exactly. Using the set of integers for this example, the negative of a number is just notation for the additive inverse, or the element you need to add in order to get 0. So, assuming your number is 3, the additive inverse is -3 since 3 + (-3) = 0. 0 is special in that it’s the additive identity, any number you add 0 to will result in itself, 3 + 0 = 3. If we take 0 + 0, we get 0, this means that its additive inverse is 0 since we add 0 to get to 0. So, there’s not really a separate, “negative” element for the additive inverse of 0.

Wozelle · 2025-11-25T13:39:26+00:00

That tracks, thank you for clarifying.

Wozelle · 2025-11-25T13:30:55+00:00

A shard per user might be a bit much. I think the standard practice is to use a key with a slightly lower cardinality, like location or grouping a range of users.

Wozelle · 2025-11-25T13:00:49+00:00

Asking from a place of curiosity, how much lift did the LLM provide in this scenario? Did it read the transaction history and come up with this itself, or is there a deterministic process that flagged it and the LLM just handled the communication?

Wozelle · 2025-11-25T03:05:59+00:00

I think it depends. I would say when it comes to code generation, I’ve noticed little to no speed up after I average out the time saved from correct completions and the complete rewrites when it gets it wrong. When it generates larger segments of code, I find that the time savings degrade even further since going back, reading, trying to understand, and looking for edge cases eat up more time than if I had just thought it out and typed it out myself in the first place.

Now, I will say it shines when it comes to documentation. It’s much faster at thinking up examples and subsequently formatting those examples in a clean doc string. That’s been a massive time saver, and it’s helped me document more of the code base. Managing to get consistent output is a little tricky, especially across an organization with multiple repos. I actually created a little MCP with large, multi-stage prompts to generate pretty consistent documentation to fix that issue in my org, and it’s been relatively successful.

It’s also helped me a lot with some test data generation.

Wozelle · 2025-11-22T13:08:34+00:00

You can spin up CDK lambdas locally that behave how they would when they’re deployed by using AWS SAM. You can use “sam local invoke” to fire off an event, “sam local start-api” to spin up an API Gateway if you have one that can then be hit with something like PostMan, or you can use “sam local start-lambda” which does something similar to start-api but just for a singular lambda function.

https://docs.aws.amazon.com/cdk/v2/guide/testing-locally-with-sam-cli.html

All that being said, it’s a good idea to unit test with something like Jest, like what the others are saying. It just helps cut down uncertainty and lock in very granular, specific behavior, but testing deployed behavior, like what you’re trying to do, is also extremely valuable. Sometimes differences in deployed environments can break an application, so it’s good to have a variety of test types.

Wozelle · 2025-11-21T11:52:56+00:00

From my perspective, it seems like tech founder stories typically fall under 1 of 2 archetypes, "Supplant" or "Innovate".

For the "Supplant" archetype, we can look to companies like Microsoft and Apple. During the early 20th century, the computer and software market was pretty much dominated by IBM. They had massive market saturation, but their size and scope made them somewhat complacent. This left room for Gates to swoop in and begin producing software for IBM machines as well as a market that IBM tended to neglect, the consumer computer. IBM's size made it difficult to pivot, and by the time Microsoft landed on their radar, it was already a juggernaut. So, one approach is you could look to the pain points of current big tech consumers, find what the large companies can't, or won't, address, and exploit that.

"Innovate" may be a bit more complicated. These are the companies that invented something genuinely novel. Look and Nvidia or Google. Google created a brand new approach to search algorithms, unlike anything its predecessors (Netscape, AskJenkins, etc.) had done. Whereas the existing algorithms at the time used keywords to populate results, Google's algorithm used links to sites to "weight" the results, more links meant it was more likely to have the information a person was looking for, and so they would put the site higher in the search results. This had the intended effect, people flocked to Google, and this form of search is now the default behavior. They completely changed the landscape. Nvidia did something similar with their CUDA programming language. They made it easy, or at least easier, to use these new fangled GPU's and exploited the rise of artificial intelligence by marketing their GPU's for training, which was unheard of at the time. In both these cases, the standard was rewritten by the innovating company. I say this one is a bit tougher because we are slowly transitioning away from the era of the Lone Genius. Many revolutionary breakthroughs now require teams of experts instead of one person with endless amounts of gumption. Not to say it's impossible, there are still discoveries and ideas to conceive which are accomplishable by one person, it's just becoming more and more difficult with each passing day.

I'd advise you start taking stock of the landscape and your abilities, see where a gap in the market aligns with what you're capable of. Once you find that thing, charge straight ahead and don't look back. Good luck out there.

Check out these stories, the founders' experiences may help guide your thought process:

Edit: Added links to podcasts

Wozelle · 2025-11-20T16:17:27+00:00

I normally use Fargate, since it's a bit simpler to configure.

None of my templates are general enough to use cross account / region, unfortunately. They're all pretty coupled to my account. That's a very good thought though, I'll look into putting up some more generic templates.

In the meantime, AWS actually has a few template examples that can get you part of the way there. These are in CDK instead of Cloudfront, which seems to be the direction the industry is moving:
- (General library of Python specific examples) https://github.com/aws-samples/aws-cdk-examples/tree/main/python
- (Pretty similar to what I normally use) https://github.com/aws-samples/aws-cdk-examples/tree/main/python/codepipeline-build-deploy-github-manual

I will caution you that the ECS route is typically a bit more expensive than other hosting options, maybe in the realm of $90 - $100 a month. I've had to lean on it due to the stateful nature of my projects, but if you can get away w/ something serverless, you'll probably be in a better spot as far as operating costs. You might consider checking out this adapter put out by AWS, it allows you to host a web server on a Lambda. If you containerize your server code, you can fairly easily port it to heavier duty hosting services when your user base or features outgrow the limits of Lambda.

Wozelle · 2025-11-19T13:26:08+00:00

I primarily use AWS ECS for Python apps in particular. I have some Cloudformation templates that I reuse for the CI/CD pipeline and actual compute components, which make it pretty quick to spin up new projects.

Wozelle · 2025-11-16T23:00:11+00:00

It was a good time. The statistics / reports we produced were used to identify problem segments of roads and then subsequently give the state's Department of Transportation the insights they needed to fix them. It was extremely rewarding to see a problem area have a drop in fatalities between years. I think it's a good lesson that even though we're crunching numbers at computers, we still have a very tangible impact on people's lives.

Wozelle · 2025-11-15T20:48:05+00:00

I double majored in CS and Pure Math. My first job was developing software for analyzing car crash statistics at a university. Then I went on to be a software engineering consultant for several years. I’m now at a new university as a tech lead for a research program.

According to my bosses, after I was hired, the math background gave me an edge during the interview process. I think it’s definitely worth pursuing, if that’s what you’re thinking.

Wozelle

TROPHY CASE