I can be almost 100% sure that one of the first things we learn of a coding language is how to put comments in our code, and if it's your first (programming) language, you won't find a great use for this, and worse, it’s likely that nobody will teach you how to do it properly.
What does it mean to have good code documentation? First of all, we need to have good code practices. It's worthless to have excellent documentation if our code is garbage, that's why we should follow some standards and patterns that will help us with our workflow, and if we do it properly, we will need only basic documentation.
How to do it
Start with the basics, DRY – Don't Repeat Yourself. Remember that if you have two or more functions or blocks that do the same or something very similar, you are wasting resources and the code will be difficult to read. That's why you need make sure that you are writing unique blocks of code, and as you can see, this is a very easy idea to understand, but you'll realize that is one of the hardest to achieve.
Keep everything simple and short, this will make the code easier to read and test, also don't forget to use correct names for functions, methods, variables, etc., that have a meaning for what they’re doing. Remember that we are trying to reduce the amount of documentation needed, so, do your best at writing the code, so it can “describe itself”.
Keeping everything within standards and patterns it's not enough, you have to be organized, at physical and logical layers. Organize your code into folders, methods, classes, separate into functions, everything must make sense and be easy to find.
For the logical part, put everything that one specific group of users have access to, these groups are often implemented as layers, services, access groups, etc.
And if even after all this good practices you still have doubts with some parts of the code, then it’s to start commenting your code. Before you start, remember that we want to keep it as short as possible and comments will only be there to provide clarity, not to fully explain what we are doing. You can include things like what's the purpose of the function and what parameters are needed and returned (if any).
And finally, do code reviews, every developer has a different logic, so it's extremely difficult to understand what other devs were thinking, so be prepare to receive criticism, but this is the path to improve ourselves in art of writing good code. Always take note of what other people says and improve there, and some day, people will understand your code faster and you will make the work easier for all of those who work with you.
As you can see, it's not a “super secret recipe” to have good practices, but most of the time we try to start coding right away and forget all this things, and in the end, we work more than we expected... so keep it simple and always share what you learn during the way, if you have any other good practice please tell us. Happy coding!
About the Author
Gerardo is a Software Engineer and Web Developer. He studied Computer Science and currently works as Web Developer for cloud based projects.