What are the best practices for ensuring your code is easy to read and understand?

Using consistent naming conventions is like "speaking the same language". It's helpful when you read your code or have someone else working with the code.

Think thorough before defining variable and its usage. Make it easy to read for usage, this can be achieved by make best comment practices. Your code should not give opportunity to malware to utilize vulnerabilities.

One thing that I have found extremely helpful by having naming conventions in our teams is during knowledge transfers, the entire process is much faster as both the trainer and the trainee can run through the codes much faster. Another thing is that it brings a discipline amongst the team to deliver the code in a particular manner.

Even small conventions often bring great success. This means that names of variables and functions should always be meaningful and written in full. You should always avoid abbreviating names to be "faster". There is no point in writing the code 2 seconds faster if the next person needs 20 minutes longer to understand it again. For example, a parameter should be called "defaultValue" rather than "defVal".

Use consistent indentation, spacing, and naming conventions throughout the codebase. This makes it easier for developers to understand the structure of the code Break down complex code into smaller, modular components with clear responsibilities. Use functions, classes, and modules to encapsulate related functionality. This improves readability and allows for easier maintenance and testing. Keep control flow structures (if statements, loops, etc.) simple and easy to follow. Avoid deeply nested structures by refactoring complex logic into smaller functions or using early returns or exits.

In my experience it is important to follow patterns that the team are advocates of. While one person can often have a specific point of view on say naming conventions software development is a team activity and so least surprise applies here to follow the team pattern. PR reviews alongside, for example, weekly engineering catch ups are a great way to direct a team pattern and provide feedback.

In my experience, this point is very essential. It is not only important for readability and comprehension that a method only does what is expected of it, but also for the stability of the product in the long term. If a function tries to cover too many functionalities, it quickly becomes very difficult to understand what the method is doing. This also very quickly leads to subsequent faults, which affects the stability of the product sooner or later. Testability also suffers quickly as a result

Each function should do only what it's meant for. If it is addition, it should not support multiplication. Keep the code easy and it will make your life easy to maintain.

I tell my teams, if you have to read comments to understand the code, the code itself should be refactored to be more human readable. The only time comments should remain is if the team can't make the code more readable due to external constraints. This means always write your code so it is in short, readable "paragraphs", and so it fully describes the business workflow it implements. Naming conventions should be flexible enough that variables (nouns) are clear, and methods (verbs) fit together in the statements (sentences) they are used in.

I cannot disagree more completely or more strenuously with the “less is more” school of commenting. I used to believe this too, and then we, against my objections, instituted a rule that write out the algorithm in comments first, then write the code to implement the comments such that if you grep the code for just comments, you get a human-readable algorithm. The result was a better algorithm, more concise code, faster development, easier and faster maintenance, and a poke yoke against strange cognitive mistake bigs. People have a visceral reaction against this because comments are somehow seen as a sign of weakness or something. Try it for a week. It will change your life. It’s a vastly underrated skill.

As mentioned by another contributor ideally code should be readable standalone due to other principles in this article ie least surprise, naming conventions etc. Comments are sometimes necessary when there are other factors at play e.g. legacy etc. Providing direction in coding as a team works well and allows flexibility as new issues arise.

There is always room for insightful comments. While it is useless to explain what the code does (if it is written well....), comments should make clear 'assertions' (namely, the anticipated values of variables upon entering a code segment) and 'motivations', or the rationale for executing the ensuing lines of code. While it's true that code should be self-explanatory (with meaningful variable and function names being paramount), reviewers or debuggers may not necessarily grasp your assumptions or the context surrounding a specific piece of code.

In today's world of agile, many try to take a shortcut by avoiding comments and other documentation. Agile doesn't mean no documentation. Optimum yet useful comments and documentation is absolutely necessary without which your code cannot be complete.

I adopt a modular approach in both creating new shell scripts and optimizing existing ones. By breaking down scripts into smaller, units or modules, they become reusable and inherently self-documenting. This not only streamlines the addition or removal of functions as needed but also simplifies the testing process, enabling the execution of specific modules. This modular design is echoed in the transition from shell scripts to Ansible playbooks. Ansible's architecture is based on modularity, comprehensive documentation and the convenience of tags for executing specific components. Modularization facilitates the inclusion of checkpoints within the code, offering a structured mechanism for halting or proceeding based on predefined conditions.

I've found that refactoring and modularizing code are pivotal steps in ensuring clarity and ease of understanding for fellow developers. By meticulously restructuring code without altering its functionality, and breaking it into smaller, self-contained modules, I've witnessed a remarkable improvement in readability, maintainability, and reusability.

Yes, refactor and modularize your code when it provides a practical benefit. Refactoring for the sake of refactoring can be a squeeze that provides very little juice. Ask these questions on whether to refactor or modularize: ? Does it make the code easier to follow? Will it help a new developer or engineer come up to speed quicker on the code base? ? Does it make it easier to edit or change and reduce the risk of introducing breaking changes? ? Does it make it easier to replace? ? Does it make the code easier to test? And finally, don’t refactor or modularize prematurely. You can do this iteratively as you mature the solution.

Consistency along with following the paradigms and best practices of the language/framework will make a code base easier to read and understand. Enforcement of coding standards and guidelines should be done by using common settings that can be exported and shared between the IDEs of the code develoarpers. Additionally, code standards should be enforced independently of developers via automation. When it comes to manual code reviews, the focus should be on can we implement some functionality that complies with our coding standards, or do we need disable a style rule based on how some functionality is implemented because doing so will increase readability and the current approach is the most elegant and maintainable.

Coding standards enable excellent readability. Some of them even though they appear simple contribute greatly to ease of understanding. Some examples: 1. Tab spaces - enable easy understanding of flows , loops and indicate flows. While most editors provide this, many developers still edit on the terminal or have different spaces for tabs etc 2. Debuggability - Any well written software will encounter issues in customer environments. It is imperative to add logs that will actually enable debugging with useful information.

I have found some team members do not sometimes feel they can provide feedback. Even the most inexperienced member of the team can provide feedback and can often help with their learning and understanding. Often this feedback can also help re-evaluate previous assumptions.

Most of humans naturally hesitant to provide feedback. Feedback consume time & energy and need to build an open culture among teams and organization to let the feedback flow smoothly. Thus, as code developer you need to stay open minded to accept comments and feedback from others, and always consider those as learnt lesson that everyone of us need to seek for

If you adopt only one principle to making your code maintainable, it is: DRY Don't ... Repeat... Yourself... Variables and function names can be refactored with tools. Indentation can be fixed with linter. Code flow can be made more readable by no-nesting and extracting method (which can be largely automated). But, if your code has many ways to do the same thing - it is larger, more complex and harder to reason about. Learn how to use functions properly and create better abstractions. By insisting on DRY code - everything else typically falls into place. Oh yeah, and don't use Java :-)

In my experience, being fanatical about inline comments as you are coding, or right after you finish debugging or re-factoring, is always a good practice. Even if no one else is going reading your code, when you come back to it, maybe months or years later, you’ll thank yourself. And if you don’t, you’re gonna be kicking yourself saying, “what the #!?# was I thinking!?”

Design your objects clearly. I have seen many instances where objects are not designed properly and that means that code is a complete web of connection between objects instead of being a simple connection between different objects. If there are two way interface connections between objects, you need to revisit to see what is incorrect in the design of the objects and how to simplify that.

Build, adopt and maintain a methods source repository containing a set of best code examples and educate your team to use and refine the code models. Augment with a strong test environment and common test routines. Encourage all to copy and contribute to the source and test models to become highly proficient and efficient. Include the basics like: read, write, validation routines, single record update, set updates, complex reporting and update functions, external data base connections, security, import & export scrubs and handlers. Really run unit and system tests. Engage user acceptance. Build a knowledge repository containing snips recordings of the business functions. Build cooperative mentorships.

To ensure code readability, use meaningful names, clear comments, and consistent indentation. Break down complex tasks, maintain a uniform coding style, and favor clarity over brevity. Keep lines short, eliminate redundancy, and document design decisions. These practices enhance collaboration and contribute to a maintainable codebase.