How can you make your code more transparent to others?

Always use meangful names and add comments. You won't remember why you added something when you comeback to same code section

Consider your audience and think forward about your code architecture when deciding on naming conventions. If you anticipate adding features later that calculate various sorts of means/averages and/or perform different related functions (e.g., calculate versus plot), you may aim for specificity in naming (e.g., “calculate_mean_geometric”). Also consider the familiarity of your users and future developers with terms. For instance, mathematicians using and developing code simulating data from different distributions may be most familiar with probability theory parameters (e.g., negative binomial successes, “r”; probability, “p”), whereas scientists may think in terms of mean and variance. Make translations accessible in documentation.

One important point to note. Don’t use the term “It works on my machine” ?? Software craftsmanship is all about writing self explanatory code that requires minimal references to external documentation!

Use everything the language and framework has to offer: Namespaces, classes and others. Personally, I like to add a small comment on top of big functions (50 lines of code or more), to let other people know what that is about.

Ensure your code is self-explanatory, clear, and clean, with proper conventions. Avoid unnecessarily complicating your code to address problems. Adopt a mindset of simplicity and clarity, thinking in a straightforward manner. Imagine reviewing your code as if you were approaching it for the first time; if you can understand its meaning in 30 seconds or less, your code is considered clean and clear, both for yourself and others.

As Bas highlighted, code should speak for itself without relying on comments. But if you do use comments, remember to update them when you change your code. Outdated comments can confuse more than no comments at all.

Comments should never have to explain what your code does. The code itself should be understandable without any comments. Comments shouldn’t be used to explain why a decision has been made. That’s documented in the way of work documents. Only in rare cases a comment can explain why a deviation has been made (i.e. performance reasons), which is only the case in high performance applications, not the rest. Readability of code over comments.

- Explain the reasoning behind certain decisions or workarounds. - Avoid unnecessary comments that restate obvious code functionality.

Comments and docstrings act as a form of documentation within your code. Adding comments to explain complex sections or providing docstrings for functions and classes helps others understand the code's logic and usage. This additional information is particularly valuable when someone else is reviewing or working with your code.

The most crucial point of following coding standards and style guides is maintainability. Consistent coding standards and a well-defined style guide make your codebase more readable and understandable. This, in turn, allows for easier collaboration among developers, reduces the likelihood of errors, and simplifies the process of maintaining and updating the code over time. adhering to coding standards also contributes to a more professional and cohesive development environment.

Adhering to coding standards and style guides ensures consistency in your codebase. When everyone follows the same set of guidelines, it becomes easier for multiple developers to collaborate seamlessly. Consistency in how the code looks and is structured improves readability and ensures everyone is on the same page.

First and foremost, I find it very important to agree on the language that is used for the documentation and naming (e.g., variables or function names). This might be surprising for most people, but it is no fun to read code in a foreign language. Good code comments can also be extremely helpful in understanding an implementation and should answer the question "why?" instead of just repeating "what" is implemented. Personally, I have yet to see a code base where tests as the only form of documentation work, while I have seen projects where this was attempted but definitely doesn't work. Tests as an additional method of documentation work nicely.

documentation can get very easily out dated, try to setup an automatic documentation tool that will update documentation each time code it chnaged. And always read that automatically generated documentation, if you as the dev can't get it, for sure the poerson reading it will not get it. So always review tools generated documentation updates. That way everything remains in line and clear. And for architecture design always update latest decision right away so documentation is reflecting those changes.

Use tools like Git to keep track of changes in your code and documentation tools to explain how your project works. Version control helps developers understand how the code has evolved over time, while documentation tools let you create detailed guides on the project's structure, dependencies, and how to set it up.

try to create a habit of writing BDD(Behavior driven development) way. this can be difficult at start but this will help you write code in a way thats developed via writing tests for a behavior and that will tell a clear story of what developer wanted code to do. as BDD show thought process of developing something instead of thinking all logic in head and implement it. write tests thinking about following questions: - how you want something to be? - how tests would pass if something you want to develop would already exist for testing? - what would be its behavior? it has changed my way of writing code totally. and it becomes more transparent to others as it shows developer's mind via tests

This is very important: Always let other programmers be close to your code and your tasks. In this profession, we are learning new techniques every day, so it's important to have this trade with other people. If you wrote a code that you think it will help others, share! Create a file on GitHub, put a short description and share it, to keep this cycle going on, where we learn and teach every day.

Ask for feedback and have others review your code. Getting input from fellow developers is a great way to improve transparency. They might catch issues you missed, suggest improvements, and bring in different perspectives. Regular feedback helps create a collaborative environment, making sure the code stays clear and understandable for everyone involved.

- Adhere to documentation practices when writing code. - Opt for simplicity over complexity and avoid incorporating unnecessary embellishments in your code. - Adopt a straightforward and clear writing approach. - Keep in mind that your code may be handled by others in the future; therefore, avoid the assumption that you will always be responsible for maintaining it.

Consider the levels of engagement people will have with your code (e.g., basic end-user, sophisticated end-user, intern helping write unit tests, developer reviewing code and/or making small contributions, developer helping with broader strategy/code architecture, developer refactoring the code, developer who will take over spearheading the codebase in the future) and write documentation aimed at that level in formats (e.g., text, subway maps) and in places (e.g., READMEs versus docstrings versus GitHub issues, wikis, and discussions versus comments) appropriate for that level.