Python on the importance of annotations

Recently participated in a game, and then see the code of the teammate programming, I think it is really difficult to swallow, almost every character to consult him, in the teacher's words, this is Shanbao programmer, so at this time I realized the importance of writing an annotation program, so specifically write an article to help you get started.

Note not only for their own later to see more clearly, or for future developers prepared, in fact, after a period of time, when the need to make some changes to the program or to correct a bug, we may forget about the future of the relevant details, so at this time the comments appear particularly important.

Each comment starts with a pound sign (#) and ends at the end of the line until the end of the line. We can put anything in the comments, because Python ignores their existence completely. In order to write a good note, here are a few rules:

(1) Assume that the reader has the same level of Python as you (for example, don't explain "what is a string" and don't explain "what is an assignment statement")

(2) Don't comment on meaningless things. For example:

Count = Count +1   #  Add one to  count

(3) Many programmers write comments that begin with "TODO" or "Fixme" in their code to remind them to come back and write or clean up some unfinished problems.

(4) If you need to think hard when you are writing a program, you should write a comment that will not be racked by others in the future. In particular, if you are in the development of the program or the function when the use of key points to describe, as far as possible to write a little more detailed, after the development work is completed, you should also leave the original point of all the two directly to explain.

(5) Similarly, if a bug is difficult to pinpoint, or if its modification is complicated, you should write a comment explaining it. If you do not, then the programmers of other complex parts of the future will probably assume that they do not need to be so complicated and change it to the original, so that your efforts will be wasted.

(6) If you need a lot of comments to explain the role of a piece of code, then the code should be organized, for example, if you need to explain the 15 list of a function, then you should split the function into smaller blocks of code, each processing only a smaller number of lists.

(7) An outdated comment is better than no comment, so after you modify a piece of code, be sure to check the comment and make the appropriate modifications to ensure that it still has the ability to accurately describe the code.

(8) Note that the more the better, the whole code is a comment, but seldom see the code, so that the meaning of the comment is distorted.

So, be sure to develop a good habit of commenting code, while writing code side notes, timely record your ideas, for example, the code is fish, notes are water, with the correct comments, fish can better survive. There is more to improve their ability to interpret the code, in a refined language to express the core value of the code, then you write the code is successful.

Here's an example.

def find_two_smallest (L):     " " Return A tuple of the indices of the smallest values in list L " " = Min (l)    = l.index (smallest)    l.remove (smallest)    = min (l)           = l.index (next_smallest)    L.insert (min1,smallest)    if min1<=  Min2:        min2+=1    return(min1,min2)

Python on the importance of annotations