The Right Way to Document Your Code

Writing comments for your code.md

The Right Way to Document Your Code

1. Readable code means we just read the code like a book, without process alot of logic behind our brain.

   • And rather understand rightaway what a piece of code does

2. Boolean expression should always keep in positive expression to minimize cognitive load

3. Comment the why, not the what.

   • Don't add comment explaining what the code did, all you're doing is adding noise to the code
   • Comments should be used only to explain the intent behind code that cannot be refactored to explain itself.
   • Mostly used for providing additional context, i.e. answering the WHY not the WHAT.
   • "Nothing can be quite so helpful as a well-placed comment. Nothing can clutter up a module more than frivolous dogmatic comments. Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation." Clean Code, Robert C Martin (Uncle Bob).

4. If u need a comment to explain what a specific piece of code does, not necessary but its a strong sign that the code is not readable

   • Go back to step 1 refactor and making the code more readable

5. Comments only useful when they explain why somethings happenes due to specific business requirement, hence the code need to structure in this way

   • Maybe need a specific workaround for a bug. For example, "If we dont do this then something wrong can happen"
   • So that if future other engineers sees the code, got comment to help understand

6. Comments especially in API docs is useful when making a library/SDK or large team project

   • Other than for public facing APIs on module boundaries, there is no reason to have any comments in code.

7. Hacks or technical workarounds

   • You can encode the why in function names themselves. So, if you need to perform a hack, then just make a function that has the why in its name.
   • Comments often go stale or even get lost in refactoring. Code does not. comments most of the time outlive the code they attempted to describe.

8. Unit tests are also a better solution to comments.

   • If you have some weird code for some random business requirement, add a test for it instead.
   • Then, this requirement will be captured programmatically. Comments do not ensure we are fulfilling our business requirements, but unit tests do.
   • Tests document how the code should behave, not just that it "does what is does".
   • Tests are examples of how to use an api, with assertions
   • Tests usually also give examples of edge case scenarios

9. Comments were probably useful when languages were much less expressive

   • But today we have programming languages that can capture our intent almost perfectly in the code itself.
   • This is why we are not necessary write comments in the code anymore. If the code does not explain itself well, then it is better to invest in making the code itself more expressive

10. Refactoring best practices

    • Whenever you want to leave a comment, extract that code in a method with a name that explains its purpose.

11. Extract a constant value out as variable for readability. For example, const val NUMBER_OF_GRID = 9

12. Git Commit Log

    • Most misunderstood
    • Gives more context about why a change is going into the codebase
    • Answers the "why is this done like that??" question
    • Flexible in terms of the amount of content, lives with the code with no clutter
    • Commit message can never get out of date.

13. Write a README.md that has higher level context such as structure of code, coding standards, design choices etc.

    • This can help you better navigate the different components of the codebase
    • Use Emoji or Alerts to give more interactive reading

14. Making the code fairly self-documenting by making good choices of class/function/var names. And adding comments that explain WHY things are being done, not how.

    • Because merge requests are reviewed by someone else, so it's a fun challenge to make sure everything is clear enough that the reviewer won't ask me any annoying questions.
    • And you want to make sure then when you come back in a year or two, it's easy for you to remember what the heck I was doing in the code
    • When that explanation becomes too hard to understand it’s time to refactor
    • Comments should provide meaningful explanations and not simply describe the syntax of the code.

15. Code should be written in a way that promotes readability and is easy to understand for other developers.

    • Good documentation can take different forms such as comments, documentation sites, and API documentation.
    • Using type hints in code improves clarity and understanding.

Reference

• https://www.youtube.com/watch?v=Bs0oGhZEqpk
• https://javascript.plainenglish.io/the-ultimate-guide-to-writing-self-documenting-code-998ea9a38bd3
• https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax