Please comment your damn code.

I stood up just to say something:

Please comment on your damn code.

Every time I meet a programmer-sometimes at a fairly high level-I always find that he thinks: you don't need to annotate your code. I'm going to say, this is nonsense. I've been saying that for a long time. The problem is that it's harder to change things than you think. While we're in the midst of trying to write nasty code and get ready to post some amazing new things, we still almost annotate everything. There is no excuse not to do these things. Every 3 to 7 lines of code, you can see a lengthy editorial published. Sometimes, in hundreds of lines of code, you can find a good joke.

The wrong place to hide

Look, one is what you want, one is what you achieve. Your bug is between the two. If you write a note, you are telling me what you want. And your code tells me how you do it. The flaw in the program is either the idea you want, or the need is right, and your code is problematic. Please help me and let me know what is wrong.

Don't be lazy.

A common objection is: I've heard that comments often expire because the code is updated frequently, and the comment does not. Don't you want to update the notes? Not even your co-workers? Don't be lazy, don't get into a culture where people think it's a bit lazy to steal. Tell your co-workers how to be meticulous in annotating the program and let them know that you want them to do the same. It is only an excuse to say that you are not commenting because you are afraid that someone or some place will cause your mistake in the future.

You're a man of experience.

It's natural to be ignorant of people, but you are experienced people. Therefore, you have compulsory education for those who need to learn. Your comments will guide the people who are reading your code. Tell them why they want to use the tuple data structure here instead of using the other (better yet, attach a stack overflow or dotnetperls link ...). You can do all this, can't you? What shortcut did you take here? If you don't take shortcuts, you won't be able to release them on time, so tell them about the special situations you're facing. Otherwise, your bad code will eventually be copied around and spread around. See! The bad code you wrote became the company's program template! No comment at all!

You can type.

Part of my recruiting process is whiteboard programming, and part of keyboard programming. All good programmers are masters of typing. Just say you can play 40-60 words per minute. So tell me, why don't you write code without a comment when you're shooting a machine gun? Of course, you can spend 30 seconds telling me that the code is so messed up because the guy who does the business needs the program to be released this week and return a hefty 75,000 dollars. But what about next month? Don't you want the code? Sealed in a rock? I know what the code is doing. But please tell me what you intend to do.

You're getting older.

Listen, I've been programming for a long time, maybe before you went to middle school. I'm still programming, and I still like programming. Someday, you'll be as old as I am. If you come to me (at that time I have no ability to retrain you), there are too many layers, there are too many abstractions, there are too many technical framework, you can not fully remember. Your comment will be able to guide you. They will tell you that 6 months ago, you did it in this way, and it was done just to show off. If you're a really good--and still programming programmer--you realize that the code is poorly written and you now need to implement it in a different way. And you still have your notes to remind you of what you were thinking and why you did it.

So, please comment on your damn code.

[English text of this article link: Comment your damn code]