How do you make your algorithms readable and reusable?

The key to both readability and reusability is to break down the mega big algorithm to smaller sub-algorithms. Each of these smaller sub-algorithms should be bite sized with descriptive method names and some documentation above the method that makes it self evident. Parametrize the logics and avoid any hard-coding. Use sensible defaults. The most interesting reuse will come with interesting combinations of these sub-algorithms and different uses of the parameters.

What I follow: 1. Comments at the top 2. Comments besides the lines where complexities are involved 3. What the code intends to do (in comments) on top. 4. The portions that can be reused are either indicated properly using comments or Macros are used with specific input variables.

To make your algorithm more readable and reusable: 1. Use meaningful variable and function names. 1. Break down complex logic into smaller functions. 2. Add comments and documentation. 3. Follow a consistent coding style. 4. Avoid overly complex or convoluted logic. 5. Modularise the algorithm. 6. Separate concerns. 7. Implement unit testing. 8. Leverage established design patterns. 9. Refactor and improve iteratively.

Well-written code can dispense comments, which can be detrimental if not maintained. One-liner docstrings describing classes/functions and attributes/arguments are sound.

What I found helpful is 1) Break entire code/ algorithm into micro sections /functions 2)Each section /function should have a top comment regarding what the intention of this section is 3)Complex part of each section should have comments on right side or underneath them to explain what is intent 4)At the end of code In comment add for a given input what will be output of different sections and what will be final output This will help clarify any doubt left on the algorithm to viewers

Include an analysis of the algorithm. The inclusion of computational complexity (time, space) is always beneficial to the developers, as they can choose from alternates to suit their requirements.

Follow the naming convention initially provided or rename everything to maintain consistency. Using x_ or _x for private variables, or s_ for strings, etc. might force you to rename everything in the future when the variable need to become public, so it is questionable if it is a good practice.

This is more of a tip for people working across many different languages. Please learn and stick to your current languages carefully if you want other people to contribute to your code. I am a long time Java dev so small, succinct and sometimes meaningless names in Golang feel weird but I learned to embrace it as that makes collaboration much easier. Data science folks in Python also have their own conventions that may not make a lot of sense to outsiders who may not find them very readable but when you follow these conventions, people can contribute and help you with your code than rolling your own.

- One thing that a lot of junior developers ignore is the importance of naming the variables, methods, classes etc. Most modern languages are designed in a way that can help us write code that tells the reader what it does. Ruby has the ability to create Domain-specific languages or DSLs using meta-programming. This enables the programmer to define their own directives.

Consistent and descriptive names for variables, functions, and classes enhance understanding and make it easier for others to comprehend the code's purpose and functionality. By following naming conventions, such as using meaningful names that reflect the role or purpose of the entity, developers can create code that is intuitive to navigate and can be easily reused in different contexts, promoting maintainability and collaboration.

Clearly define and state interfaces and contracts for your module - what its inputs are, what its outputs are, and what errors will be reported for invalid inputs. This aids testing, documentation, and reuse.

Abstraction is a double edged sword. Too much abstraction can cause confusion any create a web of dependent codebase which can be hard to deal with. When working on abstraction and modularisation, keep the logical flow of data as linear as possible.

Have a template of a new project creation with some minimal libraries for logging , configurations, folder structure, best practises for creating and calling APIs, CI/CD integration, Unit tests etc

Having the right interfaces in my opinion is the most important thing for the long term health of a codebase. Always think what part of your code can be implemented totally differently can still integrated in your larger algorithm and put it behind a well defined interface. Your final implementation with this will look very simple and readable and you can get/hire people to work more deeply on different parts of your codebase. Interfaces are also easy to mock/fake and make unit and integ testing much easier.

In my experience, you should always code to an interface. Code is clear, simple and prone to modifications if they are needed. The best you abstract code, the more readable it is. From where I stand, we should seek beauty when we code.

I usually draw a flow chart to plan the processes and also get a bird's-eye view when writing complex logic. It is easier to spot bottlenecks and decision points at a glance. I then write pseudocode for sub-processes which helps me to think through the problem thoroughly and consider any edge cases I might have missed in the initial coding frenzy. This approach has helped me to share my approach with my colleagues and foster their collaboration and feedback well before writing the complex code, thus, making it much more efficient.

As a patent attorney who has written over a 1000 software patent applications, I’d just like to note that if you intend to patent your algorithm one or more flowcharts are required so you may as well flowchart your algorithms to save a step later??????

Absolutely! I also find using flowcharts and pseudocode essential for planning complex logic and fostering collaboration. It’s great to see similar practices in action. Your approach resonates well with efficient and effective software development. Thanks for sharing!

Pseudocode provides a high-level, language-independent representation of algorithms, making it easier for developers to understand and implement them in any programming language. Flowcharts offer a visual representation of the algorithm's flow and logic, aiding in comprehension and identifying potential issues or optimizations. By utilizing pseudocode and flowcharts, developers can communicate algorithmic ideas effectively, streamline the development process, and create reusable components that are easier to maintain and modify.

Pseudocode serves as an intermediary between conceptual understanding and actual coding. It helps in identifying logical errors, gaps, and ambiguities early in the design phase. It acts as excellent documentation, helping future developers understand the intended functionality and logic. Flowcharts provide a visual way to understand the sequence of steps and decision points in an algorithm. It also helps in identifying logical errors and inefficiencies in the flow through visualization. It facilitates clear communication of the algorithm’s logic and flow to stakeholders, including those without a technical background. It assists in the initial design and planning stages, ensuring all possible scenarios and decision paths are considered.

A good test set is often the best documentation: a reader can easily see what is the way the routine is supposed to be used, its edge cases, typical exceptional situations. As for formal documentation, when it's not generated (like tech talk), it can easily be left behind the actual code.

Conventions also help in painting a beautiful pattern to improve the readability, maintainability, and quality of your code. This also helps in sharing personal thought processes when developing softwares.

To enhance the readability and reusability of algorithms, adopting coding standards and style guides is crucial. These standards provide consistency in code formatting, naming conventions, and coding practices across a project or organization, making it easier for developers to understand and collaborate on the codebase. By adhering to established standards, developers can write code that is more predictable and easier to maintain, reducing the likelihood of errors and improving overall code quality.

Writing test cases is not just about achieving high code coverage but ensuring that every possible case and scenario is thoroughly tested with unit tests and integration tests. This approach helps in testing end-to-end locally itself. Integration tests ensure that different components of your algorithm work together correctly. They help in identifying issues that might not be apparent when components are tested in isolation. Writing detailed documentation helps in understanding the technical aspects of your work. Design documentation should be completed before starting to write code. This practice helps identify and address potential challenges early in the development process.

One thing i have found useful is to have a template for your documentation. This should have certain important factors like requirement details, assumptions, tech choices, scalability, monitoring etc

A few tests can turn a 5-minute head-scratcher into a quick glance to understand what exactly the algorithm is doing and how to use it.

Documentation is critical for your team or org to reuse your algorithm. It is ideal to create a page in your Org's documentation server (For eg: Create a confluence page) explaining your algorithm, giving the context, scope of the problem that is addresses, use cases and possible directions for enhancement

Avoid Magic Numbers and Hardcoded Values: Use constants or named variables instead of hardcoded values or magic numbers. This improves code readability and makes maintenance easier.

Add working examples and tutorial. By doing this, team members can understand the basic use case and sequences of the function calls.

Separation of Concerns: Divide your code into logical sections based on their responsibilities. For example, separate input/output handling, business logic, and user interface code.

Algorithm is one of the things which humans can still do better than robots. Robots can give you implementation of an algorithm, but the algorithm itself can be made by humans in a better and creative way.

There are two aspects that are talked about here. Readability and Reusability. Readability for the whole community can be ensured through coming up with a research paper or at the minimum, create a page like a Confluence page for the people at your org to access. Reusability can be ensured by developing your algorithm in the most generic manner possible and providing it as a library or an API along with sufficient documentation for the community to make use of the same.