How do you make your web code easy for others to read and maintain?

I endeavour to write code that is human-readable, as much as possible. This means avoiding abbreviations, where possible, keeping class names short and descriptive, and not stacking comb-classes more than 3/4 deep. An exercise to see if I’ve achieved this is to look down, say the HTML structure, and see if someone could describe the layout of the page.

Following the coding standards are a must. I agree to most of the above, except the commenting part. One should aim to write the code which is self explanatory, and doesn’t need the comments. Comments can be misleading if someone forgets to update the comments when updating any parts of the code, or not adding a good explanation would also be misleading.

From all the late nights I have spent wrestling with CSS and JavaScript, here is what I have gathered: **CSS Madness**: Have you ever tried BEM for CSS? It has been a game-changer for me. That whole `.block__element--modifier` thing? It is like giving your CSS a roadmap. No more second-guessing what that class was supposed to style! **HTML Hacks**: I am all about those semantic HTML tags. They make sense. Using `<nav>`, `<article>`, and `<aside>` feels like giving the browser a little nudge, saying, "Hey, this is what this bit is about." **Git Goofs**: How often have I had to sift through vague Git commit messages? I started using Conventional Commits recently, like night and day. I wish I'd created that sooner. 🚀

Keeping things condensed is excellent, but don't be afraid to add extra lines and comments to help others find exactly what they're looking for in your file.

Making your web code easy for others to read and maintain is key to web development. A well-formulated and structured code not only benefits others, it makes your job easier in the long run

That's one of the hardest things for a programmer... Don't be afraid to be verbose, because a verbose name can be more clear when refactoring or extending your code. Short names or abbreviations sometimes make a lot of sense to you and don´t make sense to other people.

Building on the point made by Pedro, many coding challenges encourage you to solve a problem using only one line of code. Yes, that may be interesting and perhaps worthy of admiration... Unfortunately it often means the code is unreadable. It is not approachable for coders with less experience and it is often left with no comments to help with understanding. The next time you are tempted to create a variable using a single letter, think back to when you were first starting as a coder. Was it helpful to have to do all that guesswork?

As with any writing, "coding" is essentially writing for a technical audience, and to effectively communicate your intentions, you need to know your audience. Get to know your team and use meaningful names in your code. It's akin to providing a clear roadmap for your fellow developers. This practice not only enhances readability but also contributes significantly to the maintainability and collaboration aspects of web development. Rather than opting for vague or cryptic names, consider naming variables, functions, and classes based on their purpose. For instance, use 'counter' instead of 'x' to denote its role in the code.

Take every opportunity to express your understanding and the intention of the code with clear and descriptive naming. There is nothing worse than having to read chunks of code trying to figure out what the author was trying to achieve. Never abbreviate and never assume the reader of your code will have any further knowledge of the system. I can guarantee when you read the code yourself after 5 years you will have no recollection of anything that was not written down.

Variables should be named in a way that any developer can read it like a book. Otherwise, codebase will get more and more messy by the time. If your code cannot be read like a book, it can mean following: - Dirty design, therefore hard to name things write, variables include names from different contexts - Code is more imperative than declarative. It tells how to do things instead of what to do - It simply takes more time to develop a feature I suggest reading classics from Robert Martin and Martin Fowler about clean code, testing, architecture and other topics that would help to understand this deeper

While achieving perfectly clean code can be challenging, using comments can significantly enhance code readability and understanding

Comment everything. Ignore people who say don’t comment just refactor, they don’t understand encapsulation of intent. Your comments will fill in the blanks that the code is not capable of expressing such as why this needs to be done and why this approach was taken and why other solutions were not chosen. This information is critical and incredibly valuable. Don’t explain what the code is doing with comments, good code will explain itself. This is often what is meant when a refactor is suggested. But this doesn’t mean you should not comment all of the built up context that was gathered in your brain and used to create the logic. Comment everything like a story.

If your code needs comments to be understood by others then your code needs to be refactored. Comments should be avoided. Comments can still be used to mark areas of code that need attention or improvement. "TODO" comments highlight tasks that need to be completed, while "FIXME" comments indicate known issues or bugs that should be addressed.

To ensure your comments remain valuable, consider them as part of your code's narrative. Imagine that you're writing a story for a colleague who might come across your code in the future. Clear, concise, and relevant comments enhance the readability of your codebase, simplify debugging, and foster collaboration among developers. Remember, it's not about quantity but quality when it comes to comments. Avoid redundant, outdated, or misleading comments that can muddle the code's meaning. Utilize different types of comments, like single-line, multi-line, or docstring, based on the coding standard you follow. This practice ensures that your code remains not only functional but also comprehensible for your entire development team.

Comments are very helpful specially if you have short term memory. In fact, clear comments are helpful not just for you but for the whole organization by documenting well what is being executed.

A good code organization results in a more maintainable code. Splitting your content by specification can be very helpful when you reuse a code or even take a look to understand that piece of code.

Think of your code as a well-organized book. Split it into smaller, reusable units like functions, modules, or components, just as chapters make a book manageable. Group related code elements together to create cohesion. Utilize whitespace and indentation to establish a visual hierarchy, making it easier to navigate through your codebase. Incorporate headings and separators to create sections and categories, providing a clear roadmap for yourself and your team. Proper code organization is more than aesthetics; it's about reducing duplication, managing complexity, and minimizing errors. Embracing this practice is like crafting a roadmap for your project that leads to a smoother journey and fewer detours.

As a person with mild dyslexia, I find it easier for my eyes to read codes indented with 4 spaces instead of 2 spaces. Well indented code are easier to read and maintain. But in modern development tools, this can already be handled automatically.

It's always tricky with "code organization". Mostly what I see on different projects it's just organizing files into different folders, without any clear design. If you want to build clean architecture, you should first define clear boundaries of your system. There should be defined business domain logic, and periphery logic for services. All the dependencies should go one way. If this is done, then your code is already like 80% organized. Code inside implementation can actually be dirty, and this will not be such a tech debt. But if there are no clear boundaries defined, then even the most modular code approach within your code base won't help. Any feature development will take much more time because of breaking SOLID principles.

I like to say that a good test is the better documentation for your software. It doesn't mean you shouldn't write a doc, but it shows the execution of your code in a more practical way.

Using any form of test driven design is a game changer and is so rewarding even if done poorly it still holds great value. Writing tests to see how your code handles every scenario is a great thought process that will forever change the way you code. You instantly see and handle edge cases during the writing of code which results in far less bugs after the fact and far simpler solutions.

For frontend it's easier just to write e2e tests for most cases. However, if I build SDK that is going to be used across different projects, I use TDD approach to save time and make more confidence of my code. TDD (Test Driven Development) is well known approach, which tells you to write tests first, run them to fail, create implementation and make test pass, refactor, run tests again, and so on. This brings several advantages: - System requirements are documented in tests and can be run any time - No more fear of refactoring, any update can be tested, so that nothing breaks unexpectedly - Much cleaner code, because it's harder to make incorrect design when you use TDD

Based on my work experience, I've observed that creating unit tests and debugging code are crucial tasks for fully understanding a business rule and the overall functionality of the system. Unit tests allow us to validate each part of the code in isolation, ensuring that every component works as expected. Additionally, detailed debugging helps identify and resolve issues, providing a deeper understanding of the system's behavior. These practices are essential for delivering robust and reliable software.

Yesss. To add to this, follow the commenting standard of your language of choice (e.g. PyDoc for Python) for easier readability and options to compile into stand-alone READMEs

Think of code documentation as a treasure map for other developers. It encompasses crucial details like the code's purpose, features, dependencies, parameters, inputs, outputs, and real-world examples. Utilize different formats and tools, such as comments, README files, code snippets, or documentation generators, to match the scope and scale of your project. Comprehensive code documentation isn't just about helping others; it's about aiding your future self. When you return to a project months or even years later, clear documentation can save you from trying to understand your own code. Documenting your code isn't just good practice; it's a strategic move towards more effective development and seamless collaboration.

The code documentation is most important and crucial thing in this topic. Not only for others but for coder itself. The biggest challenge here is to keep documentation up to date but benefits are visible when we need to extend / change the complex functions / classes created a long time ago. Without documentation the first questions we need to find answers for are what are all impacts of change and what are all relations of function / class to the rest of software? For sure these are not pleasant questions for developers since without deep and time consuming analyze we will have no full answers. BUT with well documented code the things are easier. So, always document your code for yourself if it's more then just two loops!

Clear documentation is essential for easily gaining an overview of what is possible to accomplish. However, in practice, many companies lack documentation or have very little of it. Consequently, when someone joins an existing project, it takes some time to adapt properly to the existing code. It might take 5 - 10 minutes of your time, but it saves much more time in the long run.

Certainly! There are some additional considerations and insights to help make your code more readable and maintainable: 1. Modularize your code. It promotes code reusability and separation of concerns, reducing the complexity of your codebase. 2. Keep your code DRY (Don't Repeat Yourself) 3. Utilize a version control system to track changes to your codebase 4. Always keep dependencies and libraries up to date. 5. Format your code. Use meaningful whitespace and indentation. 6. Regularly review and refactor your code. 7. Implement robust error handling mechanisms in your code. 8. Ensure the security of your code by following best practices for data validation, authentication, and authorization. 9. Collaborate and seek feedback.

Instead of over-commenting the projects I personally prefer the approach: - initial readme for introducing the project, it's something like the trailer of a film - clean vcs messages, each git commit should have a title and a clear and efficient description of what have been done, of course adding the reference id of a jira ticket will help - where it is possible, use of a tracking tool (I've mentioned jira before) that explain the history of a functionality and evolutives - comment only methods, functions and class, if we need to comment the code inside probably we are adding some extra complexity - reduce cognitive complexity as much as we can

Since discovering Uncle Bob with Clean Code, my approach to coding has completely changed. I wish I had known about it much earlier in my learning process; it would have saved me a tremendous amount of time in my early development stages and provided a significant time-saving advantage in my early career at the company.