Write Comments Your Future Self Won't Hate
Code comments for your future self: How to write comments without being scolded by your future self
Have you ever experienced this: opening your own code six months later, reading two lines, and only thinking one thing in your mind - "Who wrote this? What the hell?" Congratulations, you are not alone. Carelessly written code comments can really make your future self "fuming", especially when you find that you wrote those comments completely "Buddhist" at the beginning. Don't panic, today's article is for you! Let's talk about how to write comments so that your future self will be less angry, lose less hair, and have less "self-doubt".
1. Explain "why", not "what"
"What is a comment?" - Many people will write like this:
a = 5 # assign a value of 5
However, when you see this comment in the future, you may roll your eyes: the code already says a = 5, what's the point of writing it again? What's more important is to tell yourself: Why should a be equal to 5? For example, write like this:
a = 5 # Set the maximum number of retries to 5 to avoid infinite loop retries
In this way, your future self will know that oh~ this 5 is not written casually, but is used to control retries. Just writing "what" is equivalent to wasting future time with nonsense; writing "why" is to save the future hairline with comments.
2. "Mysterious numbers" must be explained
Some numbers are written casually at the time, thinking that everyone can understand them, but your future self will feel like looking at mysterious symbols when they see them. These constants are also called "magic numbers" and must be explained!
Wrong example:
discount = price * 0.07
Correct example:
discount = price * 0.07 # 0.07 is a fixed discount rate, representing a 7% discount on holidays
This comment at least tells your future self: 0.07 has a history, not that you made a mistake in typing the decimal point.
3. Don't let comments become "talking to yourself"
Suppose you wrote a comment like this:
count += 1 # Add 1 to count
This kind of comment is almost useless. The code is already very clear, and this kind of "talking to yourself" comment is a complete waste of space. The purpose of comments is to provide information that the code cannot see. What really needs to be commented on is: Why do you need count + 1? Or what effect will count + 1 trigger? This will be helpful to you in the future.
4. Explain complex logic in simple language
When the code logic is a bit complicated, comments can be a treasure for your future self to find ideas. For example, when the code involves multiple steps, don't let your future self play a jigsaw puzzle.
# Check if the user is logged in -> Check permissions -> Load page content if permission is granted
if user.is_logged_in:
if user.has_permission:
show_page()
Sorting out the process in one sentence, the future you can understand the intention of the code at a glance, instead of guessing the logic of each line.
5. Mark potential "pitfalls"
When some codes are prone to errors or you use "not so straightforward" writing methods, please give a "beware of minefields" reminder for your future self. For example:
# Note: Use i-1 here, otherwise it will cause array out-of-bounds errors
result = array[i-1]
Marking this kind of "minefield" can not only protect yourself, but also protect other members of the team from stepping into the pit.
6. Explain TODO, and don't just ignore it after "TODO"
TODO is one of our most common comments, but many people see TODO and think "this is what I will do in the future", but then forget to deal with it, leaving a lot of historical problems. Explain the content and reason of the TODO task, don't let your future self just look at 'TODO' and worry.
Wrong example:
# TODO: Optimize code
Correct example:
# TODO: The current code has low performance when running on large amounts of data. Consider using binary search to optimize query efficiency
Not only does it explain the need for optimization, but it also briefly mentions how to optimize, so that the future self can get started directly without having to "remember it from scratch".
7. Humor is OK, but don't go off topic
Sometimes, in order to make ourselves feel more relaxed, we will write jokes in comments. This is actually harmless, but don't let the jokes become the main content, after all, the point is to let the future self understand the code. Jokes are OK, but don't forget to accurate information.
Example:
# This code once made me doubt my life, but its function is to detect the validity of input
if is_valid_input(input):
process(input)
This will not only make your future self smile, but also make the intention of the code clear.
8. Be careful with "zombie comments" and keep them updated
After refactoring and optimizing the code, we often forget to update the comments, resulting in the mismatch between the comments and the code. This is a "zombie comment". When your future self encounters such comments, they may have an illusion due to misleading information. So every time you modify the code, remember to check whether the relevant comments need to be updated synchronously, and do not leave "expiration reminders".
9. Write comments in a suitable language
Many people force themselves to write comments in English in order to appear high-end, resulting in a bunch of "Chinglish". Instead of spending time writing in English, it is better to use your most comfortable native language to write comments clearly and clearly. Comments are written for people to read, not for machines, so using familiar language will be more accurate.
Summary: Remember your future self when writing comments
Comments are a "map" left for your future self, so that your future self will not get lost when revisiting this code. Simple and clear, explain the logic clearly, mark the minefields and "mysterious numbers", so that your future self can see it smoothly and does not need to rack his brains to guess.
Write a good comment, you will not only thank your current self, but your future self will also be amazed "How can I be so considerate!"