“Let’s Cook!”: A Beginner's Guide to Making Tasty Web Projects

When I was a child, I loved making pancakes with my grandmother. As time went on, I became a web developer, and now, instead of pancakes, I create various web projects with my colleagues. Every time I start a new project, I’m haunted by one question: How can I make this development "tasty" not only for the user but also for my colleagues who will work on it? This is a crucial question because over time, the development team may change, or you might decide to leave the project and hand it over to someone else. The code you create should be clear and engaging for those who join the project later. Moreover, you should avoid a situation where the current developers are dissatisfied with the final product yet have to keep adding new "ingredients" (read: functions) to satisfy the demands of the "restaurant owner."

• Important note: Before I describe my recipe, I want to point out that methods can vary across different teams and, of course, they depend on their preferences. However, as we know, some people have rather peculiar tastes, so I believe it's essential to reiterate even the simplest truths.

Selecting the Ingredients: Choose Your Technology Stack

Before you start cooking a dish, you usually check what ingredients you already have. If something is missing, you go to the store or look for alternative ways to acquire them, like venturing out to pick them up in the woods. The web development process is similar: before starting your work on a new project, you need to understand what resources you currently have and what you want to achieve in the end. To prepare for creating your technological masterpiece, it helps to answer a series of questions:

1. What are the functional requirements for the project? What exactly needs to be done?
2. Is anything known about the expected load on your future product?
3. Do you have any ready-made solutions that can be reused?
4. If you’re working in a team: What knowledge and skills does each team member possess?
5. Is the programming language/framework you want to use for development still relevant?
6. How difficult and expensive is it to find developers who specialize in the chosen technologies? Even if you’re working on the project alone, always remember the "bus factor" — the risk associated with losing key personnel. Anything can happen to anyone (even you), so it’s crucial to prepare in advance for any hypothetical issues.

No Arbitrary Action: Stick to Coding Standards

How about trying oatmeal with onions? It’s hard to believe, but I once had such a dish in Kindergarten. This memory is vividly etched in my mind, and it taught me an important lesson.

Coding standards were invented for the same reason as “compatibility standards” of food ingredients. They are supposed to improve code readability and understanding by all developers on the team. We avoid debates about the best way to write code, which constructs to use, and how to structure it. When everyone follows the same rules, the code becomes easier to read, understand, and maintain (also mind that maintenance becomes cheaper this way). 

But that's not the only reason for having standards: adhering to them helps reduce the number of bugs and errors. For instance, strict rules for using curly braces can prevent situations where an operation is accidentally left out of a condition. Line length restrictions make code more readable, and consistent rules for creating conditions in an if statement help avoid logical errors. Strict rules for data types and type casting in languages with less strict typing also help prevent many runtime errors.

Coding standards help reduce dependency on specific developers, which is also good for the developers themselves since they won't be bothered with silly questions during their vacation.

In popular programming languages, there are generally accepted coding standards supported by the development team and the community around the language. For example, PEPs (Python Enhancement Proposals) are maintained and managed by the Python developer community under the guidance of the Python Software Foundation (PSF). PSR (PHP Standards Recommendations) is a set of standards developed by PHP-FIG (PHP Framework Interoperability Group) for PHP. Golang has stricter coding standards maintained by the language's developers.

However, each development team or company may have its own standards in addition to (or instead of) those supported by the community. There can be many reasons for this; for example, the main codebase might have been written long before any standards were established, making it too costly to rewrite. To maintain uniformity in the codebase, the rules may be adjusted.

There are tools for automatically checking standards, known as static code analyzers. These tools generally have a wide range of functionality that can be further expanded and customized. They can also detect errors in the code before it is released to production. Examples of such tools include PHPStan, Psalm, and PHP_CodeSniffer for PHP; Pylint, Flake8, and Mypy for Python; golint and go vet for Golang.

There are also tools for automatic code fixing code and bringing it up to existing standards when possible. This means much of this work now should not require as much manual labor and resources as it used to.

Keep Ingredients Fresh: Constant Refactoring

What happens if you don't keep the code fresh, and how can it lose its freshness? Programming languages and libraries (these are the ingredients) get updated, and with that — old ingredients rot. Establish rules on how you keep the code fresh, use automation tools, and update libraries. This advice may seem obvious, but it's frequently neglected: make sure your project's dependencies and server software are constantly monitored and regularly updated. This is especially important since outdated or insecure code presents an easy target for attackers. Just as with code checking and fixing, you don't have to manually update everything; there are numerous automation tools that can assist. For instance, GitHub’s Dependabot automatically identifies outdated or vulnerable dependencies and proposes updates.

It's also vital to automate the renewal of security certificates. Expired certificates can cause significant issues, but automating this process is a straightforward task. For instance, if you're using Let's Encrypt certificates, Certbot can automate their renewal. 

The same concept applies to server software. For larger projects with multiple servers, tools like Puppet, Salt, Ansible, or Chef can be employed to handle updates. For those working with Linux, especially Debian/Ubuntu-based systems, Unattended Upgrades can efficiently manage this. 

Taste (And Test) Along the Way

A good chef usually tastes the dish at different preparation stages to ensure everything is going according to plan. In a similar fashion, a professional developer should check not just the final, but also the intermediate results using tests. Testing is often associated with just detecting bugs. Indeed, it catches errors and unexpected behaviors before the product reaches users, improving overall quality and reducing the likelihood of issues down the line. But in fact, its importance is much bigger than that. Effective testing is crucial for delivering high-quality, dependable, and well-understood code:

1. Code comprehension: Writing test scenarios demands a deep understanding of the code’s architecture and functionality, leading to better insights into how the program operates and how different parts interact.
2. Supplemental documentation: Tests can also serve as practical examples of how functions and methods are used, helping to document the project’s capabilities and providing new team members with real-world use cases.

It’s pretty much clear that achieving 100% test coverage for complex code is unrealistic. Therefore, developers must focus on testing critical functions and essential code segments, and knowing when to stop is key to avoiding an endless cycle of testing. Also, testing can consume significant resources, especially during the early stages of development. So, it’s important to strike a balance between the necessity of testing and the available time and resources.

Chef’s Logbook: Add a Pinch of Documentation

It’s common knowledge that many famous types of food, like mozzarella, nachos, and even french fries, were discovered by accident. Others took decades to develop through countless trial and error. In both cases, all of them would be just one-off products if knowledge about them could not have been passed on. It is the same with tech: each project needs proper documentation. The lack of such paperwork makes it much harder to identify and fix errors, complicates maintenance and updates, and slows down the onboarding process for new team members. While teams lacking documentation get bogged down in repetitive tasks, projects with well-structured documentation demonstrate higher efficiency and reliability.

According to the 2023 Stack Overflow Developer Survey, 90.36% of respondents rely on technical documentation to understand the functionality of technologies. Yet, even with documentation, they often struggle to find the information they need, turning to other resources like Stack Overflow (82.56%) and blogs (76.69%). Research by Microsoft shows that developers spend an average of 1-2% of their day (8-10 minutes) on documentation, and 10.3% report that outdated documentation forces them to waste time searching for answers. The importance of documentation is also a significant concern for the academic community, as evidenced by the millions of scientific publications on the topic.

Researchers from HAN University of Applied Sciences and the University of Groningen in the Netherlands identified several common issues with technical documentation:

1. Developer productivity is measured solely by the amount of working software.
2. Documentation is seen as wasteful if it doesn’t immediately contribute to the end product.
3. Informal documentation, often used by developers, is difficult to understand.
4. Developers often maintain a short-term focus, especially in continuous development environments.
5. Documentation is frequently out of sync with the actual software.

These “practices” should be avoided at all costs in any project, but it is not always up to developers. Getting rid of these bad habits often involves changes to planning, management, and long-term vision of the entire company from top management to junior dev staff. 

Conclusion

As you see, food and tech project development (including, but not limited to web) has a lot in common with cooking. Proper recipes, fresh and carefully selected ingredients, meticulous compliance with standards, and checking intermediate and final results — sticking to this checklist is equally essential for a chef and for a developer. And, of course, they both should ideally have a strong vision, passion for what they do, and a strong appetite for innovation. I am sure you recognize yourself in this description. Happy cooking!