Documenting your source code

Adding comments to your source code is an important part of software development. You will need to balance the need for documentation with the goal of keeping the codebase clean and maintainable. Every comment means extra work in the future when something changes because you must update the comments to match the code changes.

When should you document your source code?

Code can be over-commented, and it’s not necessary to comment on everything. Let’s review when developers should add comments to their code:

• To explain “why” more than “what” or “how”. The code itself should be clear enough to explain “what” it does and “how” it does it, through meaningful variable names, function names, and a clear structure aka self-documenting code. These days, “what” and “how” can also be easily explained using GitHub Copilot Chat. Therefore...