Transform Your Codebase: Best Practices Inside


Dev Team Best Practices: Leveling Up Your Codebase

Hey there! Welcome back to Founder Mode! This week, I went through the codebase with the development team in our meeting. I want to share tips to help your teams build better, more manageable software.

As we all know, building great software isn't just about writing code. It’s about putting in place a system that helps your team work well and lets your software grow. Good practices help, whether you lead a small team or work alone. They can prevent problems down the line.

Let’s dive into what I’ve learned.

The State of Many Codebases

I saw some common issues in the team's repositories. Many growing teams deal with these problems. These problems hurt code quality. They slow down productivity. This also makes scaling harder.

Some of the challenges I encountered included:

  • Repository names are inconsistent. This confusion makes it hard for new team members to grasp the system architecture.
  • README files can be outdated or missing. Often, they just have boilerplate text. This text doesn't explain the repo's purpose or how to set it up.
  • Branch management issues happen if the default branch isn't the one in use. For example, using "dev" or "development" in place of "main" or "master" can lead to confusion.
  • Old branches from merged or abandoned PRs are piling up in the workspace.
  • PR descriptions were too brief. Comments like "fixed it" or "changes" lacked context.
  • No CI/CD pipeline to validate that code even compiles before merging.
  • Large files with over 1600 lines of code are tough to maintain and debug.
  • No automated testing or quality checks in place.
  • Hard-coded credentials and config values threaten security.

Simple Improvements with Big Impact

I shared some best practices. They can boost codebase quality and make the team more efficient. Here are the improvements I recommended:

1. Repository Organization

  • Use consistent naming conventions across repositories. This helps new team members understand the system. It also reduces confusion.
  • Clean up unused branches regularly. Stale branches clutter the workspace. They can also lead to merge conflicts.
  • Make the default branch (main/master) the active one. This is the standard and ensures the correct workflows are in place.
  • Set branch protection rules. This keeps important branches safe from errors.

2. Documentation

  • Create detailed README files for every repository, explaining what the repo does, how to set it up, and how to run it.
  • Document key features, endpoints, and architecture decisions. This cuts down on questions from new members and speeds up onboarding.
  • Try using AI tools like ChatGPT to draft your documentation from the code. This can make the process easier.

3. Code Quality Automation

  • Implement GitHub Actions for basic CI checks. This ensures that your code compiles and runs basic tests before it’s merged.
  • Use linting tools like ESLint for JS/TS and Ruff, Black, or MyPy for Python. They help catch style and syntax issues early.
  • Set up automated testing. Start with basic smoke tests to check if the application works well.
  • Run a dependency scan. This will help find security vulnerabilities automatically.

4. Pull Request Workflow

  • Write descriptive PR titles and descriptions. A clear PR title and description need to show what changed, why it changed, and what was tested.
  • Add screenshots or demo links to show what your changes are.
  • Require reviews before merging. This makes sure we catch bugs early and maintain quality control.
  • Enable auto-delete of branches after merging. This keeps the repo tidy and avoids confusion.

5. Code Structure

  • Break monolithic files into smaller, modular components. This improves readability and maintainability.
  • Use package managers like npm or pip. Lock files make sure things remain the same in various environments.
  • Separate configuration from code. Store configuration values in environment variables. You can also use a secrets management system. Don't hardcode them in your codebase.

Using AI as Your Dev Partner

One of the most powerful tips I shared was how to leverage AI tools to improve your codebase. Here are some ways AI can be a partner in development:

  1. Code Reviews: Upload your code to ChatGPT. Then, ask, "Can you review this code?" What are the risks, and how can we improve it?" It will point out issues such as credential leakage, unbounded concurrency, and empty try/catch blocks, plus others.
  2. Quality Backlog: Use AI to create a "quality backlog" document. This document will list all issues found and sort them by priority. (You can use Manus to even create issues for you - Just give Manus a PAT (GitHub personal access token - it can then make issues)
  3. Automated Fixes: Use tools such as Devin AI or Cursor. They can automatically fix common problems.
  4. PR Descriptions: Use AI to make clear descriptions for your PR updates.
  5. Test Generation: Have AI write basic tests for your code to save time.

I showed how I uploaded a zip file of their codebase to ChatGPT. In about 10 minutes, it provided a detailed analysis. This analysis found security risks, performance issues, and gaps in best practices.

The Real Value

The key insight I shared was not about tools or practices. It was about mindset:

"These practices aren’t just bureaucracy—they make your job easier. When checks are in place and well-integrated into GitHub, I can approve PRs from my phone because I know if the checks passed, the code at least compiles and basic functionality works."

It's easier to adopt these practices now than to add them later when your team expands. Solo developers also gain from these practices. They create self-documenting work. This makes debugging simpler and lets new team members jump in easily.

Robert C. Martin (Author of "Clean Code")

"The only way to go fast is to go well."

This shows we need quality in development. Take your time with code. A good start boosts productivity and leads to lasting success.

Focusing on clean code and best practices from the start sets your team up for success. Skipping these important practices may feel like a fast way out. But in the end, it will slow you down as problems build up over time.

Final Thoughts

Improving practices isn't about blaming past efforts. It's about enhancing what already works well. Your teams are creating amazing things. These practices make work easier and lower stress.

What best practices have you found most valuable for your dev teams? I’d love to hear your experiences.

Happy coding!

See you on Friday,

-kevin

Recent Social Posts

twitter profile avatar
Kevin Henrikson
Twitter Logo
@KevinHenrikson
video
8:37 AM • Jul 4, 2025
2
Retweets
5
Likes

Recent Podcasts

video preview
show
15-Minute Workout with Lou P...
Jul 3 · Founder Mode
14:30
Spotify Logo
 

Catch up on past emails here.

2810 N Church St #87205, Wilmington, DE 19802
Unsubscribe · Preferences

Founder Mode

Founder Mode is a weekly newsletter for builders—whether it’s startups, systems, or personal growth. It’s about finding your flow, balancing health, wealth, and productivity, and tackling challenges with focus and curiosity. Each week, you’ll gain actionable insights and fresh perspectives to help you think like a founder and build what matters most.

Read more from Founder Mode
Coach Lou shares fitness strategies to build mental strength, resilience, and daily habits founders need for lasting business success.

Episode 15 - Onshore to Offshore to AI with Shuja Keen In this episode of Founder Mode, Jason and I chatted with Shuja Keen. He’s an expert on technology, business, and AI's future. He explained how businesses have changed. They shifted from onshore to offshore. Now, they are focusing on AI automation. Why AI Matters Today Shuja explains today's situation clearly: “People want an Uber, but they're being sold car parts. They just want to go from point A to point B. The goal isn't to sell...

Learn how to stay ahead of cash flow problems in your bootstrapped business. Discover proactive strategies to manage cash, avoid hidden expenses, and thrive.

The Psychological Price of Bootstrapping: Being careful and and extra conservative with cash Welcome back to Founder Mode! Today, I want to talk about bootstrapping and why we must be careful with cash. Happy 4th of July for those in the US As many of you know, bootstrapping a business doesn’t come with the luxury of a big cash buffer. Every dollar counts, and there’s no room for careless spending. It’s more than financial discipline. It’s a shift in mindset. This change helps you thrive. It...

Coach Lou shares fitness strategies to build mental strength, resilience, and daily habits founders need for lasting business success.

Episode 14 - 15-Minute Workout with Lou Perrotta In this episode of Founder Mode, Jason and I chat with Coach Lou, a famous fitness trainer. Coach Lou helps founders remain sharp, in body and mind. He has coached athletes and business leaders for more than 50 years. His training equips founders with the focus and grit they need to succeed. Kevin explained how important Coach Lou has been for his own mindset: “It’s incredible what you can do in such a short time with focus. During those 15...