This health check is the first step toward building better software for startups. It helped me build a couple of successful MVPs, and these guidelines guide me in every tech decision.
How to execute the health check:
- Grab your dev team and book a two-hour meeting. Don’t include business partners or other stakeholders; it has to be an internal meeting just for developers. If you don't have a senior leader who can lead the meeting, get an outside facilitator.
- As a team, go through every point and evaluate it on a scale from 1 to 10. Note your answers. If you are not sure what some rule means, Google it, and make sure you understand every word from the document.
- During the discussion, collect action points, especially when something scores less than 4.
- Calculate the average score, combine your action points into a single action plan, and send it to your stakeholders.
Development
Code is clean if it can be understood easily – by everyone on the team. A developer other than its original author can read and enhance clean code. With understandability comes readability, changeability, extensibility, and maintainability.
General rules
- Follow standard conventions. Have conventions for naming, function length, quotes, etc. Utilize Linker to control the quality.
- Keep it simple stupid. Simpler is always better. Reduce complexity as much as possible.
- Boy Scout rule. Leave the campground cleaner than you found it.
- Always find the root cause. Always look for the root cause of a problem. Don’t do quick fixes; avoid IFs.
Design rules
- Keep configurable data at high levels.
- Prefer polymorphism to if/else or switch/case.
- Prevent over-reconfigurability.
- Use dependency injection.
- Follow the Law of Demeter. A class should know only its direct dependencies.
- Utilize types; don’t use any.
Understandability tips
- Be consistent. If you do something a certain way, do all similar things in the same way.
- Use explanatory variables.
- Prefer dedicated value objects to a primitive type.
- Avoid logical dependency. Don’t write methods that work correctly depending on something else in the same class.
- Avoid negative conditionals.
Names rules
- Choose descriptive and unambiguous names.
- Make meaningful distinctions.
- Use pronounceable names.
- Use searchable names.
- Replace magic numbers with named constants.
- Avoid encodings. Don’t append prefixes or type information.
Functions rules
- Small.
- Do one thing.
- Use descriptive names.
- I prefer fewer arguments.
- Have no side effects. (or have as little as possible)
- Don’t use flag arguments. Split the method into several independent methods that can be called from the client without the flag.
Comments rules
- Don’t add obvious noise.
- Don’t comment out the code. Just remove. You can find it in Git.
- Use as clarification of code.
- Use as a warning of consequences or as a clarification of a decision.
Source code structure
- Separate concepts vertically.
- Dependent functions should be closed.
- Similar functions should be close.
- Place functions in the downward direction.
- Declare variables close to their usage.
- Keep lines short.
- Use white space to associate related things and disassociate weakly related.
- Don’t break indentation.
Objects and data structures
- Base class should know nothing about their derivatives.
- Prefer non-static methods to static methods.
- It is better to have many functions than to pass some code into a function to select a behavior.
- Do one thing.
- It should be small.
Code smells
- Rigidity. The software is difficult to change. A small change causes a cascade of subsequent changes.
- Fragility. The software breaks in many places due to a single change.
- Immobility. Parts of the code cannot be reused in other projects because of the risks involved and the high effort required.
- Needless Complexity.
- Needless Repetition.
- Opacity. The code is hard to understand.
Architecture
Architecture has to be supported by a developer, not a burden. Well, design architecture makes you more efficient. You never have to be scared to deploy your code, add a new environment variable, or create a new microservice.
- Document your backend endpoint; you will say thank you in the future (SwaggerUI, tags, examples, descriptions)
- Make your backend stateless so that you can quickly scale it horizontally.
- Automate everything that requires you to spend a small amount of time daily. Have CI/CD and an automated linter.
- Make sure your secrets are separated from the code.
- Your infrastructure must be easy to develop locally. If you have many components that require setup, like DBs, utilize the power of Docker and Docker Compose.
- Make your infrastructure observable on the front end and back end. Tools like Fullstory, Smartlook, and Google Analytics make the front end observable, and tools like Prometheus and Grafana make the backend and infrastructure observable.
- Do smart logging. Separate your logs into separate threads. If something happens, you have to be able to find the root cause just from the logs.
- Local and staging testing before deployment to the backend. Never deploy directly to production. Build expectations with a business that code must go through the testing circle before delivery.
Project management
Even a small startup is a project, and it needs management. Bad project management will make your co-founders and employees hate work. Good project management will make work feel like a vacation and will get the most out of everyone.
- The team trust each other, and there is a feeling of team responsibility.
- Execute daily meetings with daily standups. If you feel the standup is too long, separate the dev standup from the business standup.
- Don’t merge anything in the master without a code review.
- Stick with 1-week sprints and do sprint planning every Monday.
- Utilize specialized project management software like Jira, Asana, Notion, or Click.
- Organize weekly planning. The CTO or founders can do the planning but don’t forget to present it to the team and do the estimating together.
- Organize retrospectives from time to time, at least once per month.
- Strategically utilize tech debt. Let your engineers add more points if they think some features or optimizations can be postponed.
- Execute roadmap planning once in 1/2 month with all stakeholders and, optionally, the dev team. Prepare a visual board for this meeting and discuss every feature before putting it on the roadmap.
If you need any clarification or are seeking help over executing or reacting to the health check, drop me a message at yev.rachkovan@gmail.com.