When writing Python code, make sure your code easier to understand by other people is very important. To a variable, the function name from the appropriate and rational organization of the code is a good way.
Use the comment is to add another simple and easy readability of the important methods!
We will introduce some of the basics of Python written comments. You will learn how to write clean, elegant, simple notes, and know when you may not need to write any comments.
# Why is so important commented code
Note is an integral part of any program, or they may be in the form of comment blocks in lines of code, interpreted to help clarify a complex function.
Before delving into the different types of comments, let us take a closer look at why the code comments so important.
Is assumed in the following two cases, the code the programmer does not annotate.
# When reading your own code
A client at the last minute they want to deploy Web services, the deadline is fast approaching, so you decide to put it to good overall, all the "extra" things to add after such as documents, an appropriate comment, and so on.
Eventually, when the deadline, timely deployment of Web services.
But when you have not come and add comments, you have ushered in a new project boss asked to start right away, making new projects at the same time, you might put the code A customer comments forgotten.
Six months later, the same customer service A need to build a patch to meet the new demands. Maintenance It is your job, because you are the first person who builds it. After opening a text editor ......
# "I wrote before in the end what?!"
You spent hours analyzing your old code, but you are completely lost in the shuffle. You were a hurry, not properly named variables, not even set up an appropriate function in the control flow. Worst of all, the script does not have any comments tell you what's what!
Developers tend to forget things done their own code, especially if the code was written a long time ago, or prepared under great pressure. When the deadline is coming up, a few hours before the computer cause bloodshot eyes, this pressure can be more confusing than usual code form reflected.
Once submitted projects, many developers will be too exhausted, could not come back to annotate their code. After the re-use to it, it may take several hours to analyze what they have written.
While writing the code while writing comments are ways to prevent this from happening is a very good, please be kind to your future!
# When someone reading your code
Suppose you are the only developer in a small Django project, feel good understanding of their code, so you do not tend to spend more time writing notes or any other documentation.
Probably by the end, your "little Django project" has become a "20,000 lines of code," the project, and your supervisor is arranging more developers to help maintain it.
New developers work hard to quickly put in, but in the first few days of cooperation, you will realize that they will encounter some trouble. In the project code, you use some strange variable names, and use the syntax to write a super simple. This leads to new employees will spend a lot of time traversing your code line by line, in an attempt to figure out how it works.
In this case, use the comments in the code can be a good help other developers to understand your code, you can help collaborate with other developers of the project from the outset by the code comments.
# How to Write a comment in Python
Now we know why the code comment is so important, so let's look at some basic knowledge about comments, in order to be familiar with how to use it correctly.
#Python comment foundation
Write a comment to use Python, simply "#" on the content before your comments:
Python will ignore all the content after the # mark the end of the line, you can insert them anywhere in your code, and even can be used in lines of code:
When you run the above code, you will only see the output This will run, others will be ignored.
Comments should be short, appropriate, to the point. PEP 8 recommended code is maintained at 79 or less characters, line of comments in the code up to 72 characters. If your comments approaches or exceeds this length, you need to turn it into a multi-line comments.
Python multi-line comments
Unfortunately, Python can not write like that with C, Java language and Go multi-line comments:
In the above example, the program will ignore the first line, but other line will lead to a syntax error.
In contrast, a language like Java can be easily extended to multi-line comments:
The program will automatically ignore / and everything between /.
Although Python is no such multi-line annotations, but you can create multi-line comments in Python, there are about two simple methods.
The first method is that behind every row simply pressing the return key, to add a new tag #, then continue NOTE:
The program will ignore each line beginning with # mark.
Another method is to use a multi-line comment string packaged in a group of three quotes:
This comment is similar to Java in multiple lines in Java, all types of content in the ternary quotes will become a comment.
While this seems to provide a multi-line annotations, but technically, this is not a comment. It is just a string that is not assigned to any variable, so the program does not call or refer to it. However, it will be ignored at run time and do not appear in the bytecode, so it can effectively act as a comment.
However, when placing these multi-line "comment" Be careful. According to their position in the program, they can be converted into the docstring of times, which is associated with the function or method associated document fragment. If you leave these "Notes" into them after the function definition, then you want to become the content of the comment will be associated with the object. When using this multi-line comments to be careful, if in doubt, be safe to add a # mark on the back of each line.
#Python comment shortcuts
Each time you need to add a comment, type the # mark may be very cumbersome. So, what we can do to speed it? Here are some tips to help you add notes faster.
The first is the use of a plurality of cursors, the task is accomplished by placing the cursor on the screen a plurality. When left-click, simply hold down the ctrl or cmd key, you will see flashing on the screen line:
When you need to annotate the same thing in more than one place, this is the most effective.
If we have a long text annotation you need it? Or batch code into a comment, line by line comments it may take a lot of time! In this case, simply select the required lines of code as a comment on a PC and press Ctrl + /, or on a Mac Cmd + /:
All pre-selected code will add a # mark, and to ignore.
If a comment line number is more, or scripts are reading the comments in the very long, so your text editor may let you choose to use the small arrow to the left of folding them:
Just click the arrow to hide comments can be. If a long comment docstring dispersed in a plurality of rows, or occupies most of the program start-up time, this method works best.
The combination of these tips will make your code comments quick and simple.
#Python Best Practice Notes
Know how to write comment is very important with Python, it is equally important to ensure that the comment is readable and understandable resistance.
The following tips can help you write really code for your comment.
# When writing the code for yourself
By properly annotate their code, programmers can make their life easier. Even if no one else will see it, but then you might look at it again, this is reason enough for you to add comments to it. After all, you are a developer, you should make your code easier to understand.
Write a comment for himself a very useful trick is to code it as an outline. If you are unsure how to develop your program, you can use comments to keep track of the remaining work, or even as a way to track the flow of high-level program. For example, to outline the annotation function using pseudocode:
These comments are plans out get_top_cies, show that you know exactly what you want to do your function, the back can easily be translated into code.
The use of such notes can help you keep a clear head. When traversing your program will know to get a full-featured script, what needs to be done. After the comment "convert" into the code, remember to remove any comments have been made redundant, so that your code can be kept clear and clean.
You can also use comments as part of the commissioning process. Comment out the old code and see how it affects your output. If you feel the output to meet the requirements, then you can remove the comment out code in a program to improve the readability of the code. You can also use the program version control, easy to get back behind the old code.
Finally, use annotations to define the tricky part of their code. If you drop an item, months or years and then return to it, you will need to spend a lot of time to re-familiar with what you wrote. Just in case you forget your own code to do anything to help you in the future a favor, add comments to, so that later it easier to more quickly re-read it.
# When writing the code for others
People like to jump around when reading text messages while reading the code as well. When the code is out of the question that you have to figure out what happened wrong in the end, you just might read the code line by line.
In most other cases, you will quickly browse variable and function definitions, in order to get points. Things simple with comments explaining what is happening, can really help developers understand what to do in this position.
Please be kind to your colleagues, with comments to help them navigate your code. If you have a complex method or function name is not easy to understand, you may need to add a brief comment after the def line to illustrate the problem:
This can help other developers browsing your code to understand the function of the function.
For any public function, we all want to try to contain an associated docstring, regardless of whether it is complex:
This string becomes .__ doc__ properties of the function, and associated with the particular official method.
PEP 257 Guide line docstring of how the agreement. These documents string appears at the top of the file, including high-level overview of the entire script and it should do:
Module-level document string like this would include any relevant information or need to know, for developers to read. When writing a function, it is recommended to list all the classes, exceptions and functions, as well as a summary line for each class.
Python Notes worst practice
As written in Python annotation good standard, as there are several types of comments should be avoided. Here are some examples.
# Avoid: WET comments
Your comments should be DRY, which is "Do not Repeat Yourself." Abbreviation means that your code comments should be little or no redundancy. You do not need a period sufficient to explain their code comments as follows:
We can clearly see, a return value, so there is no need to specifically declare it in the comments. This is WET comments, meaning "wrote everything twice", can be understood as "wasted everyone's time".
WET comment may be a simple error, especially if the comment before writing code to the planning code. However, once the code is running well, we must return to delete unwanted comments.
# Avoid: use annotations to make up the code
Comment your code sometimes reflect deep-seated problems that may exist, the comment is a way to try to hide the code for their own problems, but comments should support your code, rather than trying to make up for it. If your code is poorly written, so any comments will not fix it.
Let's take a simple example example:
This code is very irregular, there is a comment before each line interpreter code. By specifying a reasonable name for variables, functions and collections, this script can be easier, as follows:
By using naming easy to understand, we can remove all unnecessary comments, and to reduce the length of the code!
Notes general much shorter than they support the code, if you spend too much time explaining things you have done, then you need to go back and reconstruct, to make your code more clear and concise.
# Avoid: rude comments.
This is likely to occur during the development team questions. When several people are treated the same code, others may check what you have written and make changes. Sometimes, you may encounter one who dares to write such comments people:
This behavior is very bad, if you accidentally put the annotations stay in there, then a customer sees it, this will be very embarrassing. You are a professional, adding vulgar words in your comments will be degrading their own identity.
Conclusion #
Learn to gracefully use the comment is valuable, you will not only learn how to write clearer, more concise, and no doubt you will have a deeper understanding of Python.
You know how to make all developers can use Python comment (including your own) programming life easier! They can help other developers to quickly understand your code, and help you re-familiarize yourself with the old code.
Note that when using annotations attempt to explain or make up for bad writing code, go back and modify your code is the better choice. Code comments previously written, whether it is your own code or other developers code, a good way to write a comment in Python are to practice.
Recommended reading:
Basics zero Python's most detailed source of tutorials
2019 Python Reptile Learning Roadmap full version
Why Python can be firmly secured the first card AI Artificial Intelligence Language
Python rise, TIOBE list of programming languages a new high!