Comments and Docstring
Comments in Python start with the hash character,
# Single Line Comment
A comment may appear at the start of a line or following whitespace or code, but not within a string literal. A hash character within a string literal is just a hash character.
Multiline comments don't actually exist in Python
As part of the Python course it is taught that in order to do a multiline comment one should use """triple quotes""". This is wrong. Python only has one way of doing comments and that is using # infront of every line.
Triple quotes are treated as regular strings with the exception that they can span multiple lines. By regular strings I mean that if they are not assigned to a variable they will be immediately garbage collected as soon as that code executes. hence are not ignored by the interpreter in the same way that #a comment is.
The only exception to the garbage collection fact is when they are placed immediately after a function or class definition or on top of a module, in which case they are called docstrings and made available via the special variable myobj.__doc__.
""" Three double inverted Commas for multine Comment """
You can use multi-line strings as multi-line comments. Unless used as docstrings, they generate no code! :-)
NOte : Docstrings -- First line right after function or class defination
Difference between docstring and Multilinecomment
Using a docstring means you are explicitly marking something as documentation. Comments aren't for documentation. They are for explaining why the code is the way it is.
An IDE can display them as part of their tooltips or a documentation application can compile them into usable HTML documentation.
The docstring is turned into the __doc__ attribute of the function object. As such, it can be programmatically accessed by other code, such as documentation generation systems (e.g. pydoc), IDEs, help viewers, whatever. Comments are just comments; they are completely inert.
Python documentation strings (or docstrings) provide a convenient way of associating documentation with Python modules, functions, classes, and methods.
An object's docsting is defined by including a string constant as the first statement in the object's definition.
It's specified in source code that is used, like a comment, to document a specific segment of code.
Unlike conventional source code comments the docstring should describe what the function does, not how.
All functions should have a docstring
This allows the program to inspect these comments at run time, for instance as an interactive help system, or as metadata.
Docstrings can be accessed by the __doc__ attribute on objects.
Docstrings can be accessed through a program (__doc__) where as inline comments cannot be accessed.
Interactive help systems like in bpython and IPython can use docstrings to display the docsting during the development. So that you dont have to visit the program everytime.
Documentation Strings
>> def my_function():
... """Do nothing, but document it.
...
... No, really, it doesn't do anything.
... """
... pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.
...
... No, really, it doesn't do anything.
# Single Line Comment
A comment may appear at the start of a line or following whitespace or code, but not within a string literal. A hash character within a string literal is just a hash character.
Multiline comments don't actually exist in Python
As part of the Python course it is taught that in order to do a multiline comment one should use """triple quotes""". This is wrong. Python only has one way of doing comments and that is using # infront of every line.
Triple quotes are treated as regular strings with the exception that they can span multiple lines. By regular strings I mean that if they are not assigned to a variable they will be immediately garbage collected as soon as that code executes. hence are not ignored by the interpreter in the same way that #a comment is.
The only exception to the garbage collection fact is when they are placed immediately after a function or class definition or on top of a module, in which case they are called docstrings and made available via the special variable myobj.__doc__.
""" Three double inverted Commas for multine Comment """
You can use multi-line strings as multi-line comments. Unless used as docstrings, they generate no code! :-)
NOte : Docstrings -- First line right after function or class defination
Difference between docstring and Multilinecomment
Using a docstring means you are explicitly marking something as documentation. Comments aren't for documentation. They are for explaining why the code is the way it is.
An IDE can display them as part of their tooltips or a documentation application can compile them into usable HTML documentation.
The docstring is turned into the __doc__ attribute of the function object. As such, it can be programmatically accessed by other code, such as documentation generation systems (e.g. pydoc), IDEs, help viewers, whatever. Comments are just comments; they are completely inert.
Python documentation strings (or docstrings) provide a convenient way of associating documentation with Python modules, functions, classes, and methods.
An object's docsting is defined by including a string constant as the first statement in the object's definition.
It's specified in source code that is used, like a comment, to document a specific segment of code.
Unlike conventional source code comments the docstring should describe what the function does, not how.
All functions should have a docstring
This allows the program to inspect these comments at run time, for instance as an interactive help system, or as metadata.
Docstrings can be accessed by the __doc__ attribute on objects.
Docstrings can be accessed through a program (__doc__) where as inline comments cannot be accessed.
Interactive help systems like in bpython and IPython can use docstrings to display the docsting during the development. So that you dont have to visit the program everytime.
Documentation Strings
>> def my_function():
... """Do nothing, but document it.
...
... No, really, it doesn't do anything.
... """
... pass
...
>>> print(my_function.__doc__)
Do nothing, but document it.
...
... No, really, it doesn't do anything.
0 comments:
Post a Comment