Hey, hi again and in this lecture you're going to learn how to comment and document
your code and that's very simple actually. So what do I mean by commenting and
documenting? Well commenting, let's suppose you write the script and then you
want to give that script to other programmers or you're just working in team
with other developers and what you want to do is you want to find a way to
document your script to your colleagues. And that's what's commenting is about.
So comments are these, so you start with a hash tag and you write whatever you like.
Let's say create empty file, so what I did here is you know I had this script that
what this script does is it has a function, that function creates an empty
file called sample1.txt, and if you give this script to someone else and they
may try to read the code and understand what you're doing there,
but alternatively you can help them by adding here a line that is not read as
code by Python, so Python ignores everything that gives inside a hash tag.
Basically the way you do this is you know before writing the function you
create, you write this comment and that comment basically means that you're
pointing to this block of code. Now be careful, if you click enter and start
something here this will be read as code by Python, so comments are in line.
You cannot have them in another line. If you want you can of course do this if you
want to add more lines. You can also write something beside some code, so for
instance writing empty string and everything will work fine and yeah,
that's about comments and we also have doc strings which allow us document our
code and you know with documentation what I mean is let's say import OS and
then if you do OS dot doc now you get the doc string, so this is
called the doc string and what it basically is, is some basic information
about the library or the module or the package that you are importing,
that you are using in Python and yeah you can do the same, so if you import example
what you do, you're importing the example.py as a module and if you say example
and underscore underscore doc underscore underscore, in this case you don't get
anything because you don't have a doc string in your file, so if you want to
give some information about your script to other people, you may want to add a
line here with triple quotes like that and between those triple quotes it comes
the doc string and that'll be something like you know this script creates
an empty file and if you save that, you go to the command line and if you, well you
wouldn't be able to access it right away if you try like this, so it's still empty
because Python is still holding the old version of your example module and by
the way to import a Python script as a module you need to be in the same
directory with your file, Python script, so I open this come online in the current
directory and yeah to get a doc string you can either close this session, so the
interactive session and then open a new Python session again an import
example.py and access the doc string. Or if you want you can do another trick.
You import in the library, then you say imp.reload and then you pass example, so the
name of the module you want to reload. Yeah, then you do the same thing and then
you get the doc string in there. Similarly you can have doc strings
inside functions and so. This function creates an empty file like that.
Go to the command line. Let me try exiting this time,
so exit the script. Start again. Import example.
Example.create file dot doc and you get the line in there so this function, this and this.
It should be this function, anyway this function creates an empty file, and as
you can see you can access functions from your module using the dot notation.
You know if you do like that and that will execute your function, your Python
function and it will create the sample.txt file. So let me try that by just deleting this.
Delete that and we execute again. And example.txt is there now.
And a last illustration, you know doc strings you can find them in Python modules as well.
As you see here we have os.py which I demonstrated earlier and
you see the doc string in here, the beginning of file. You can see R as well
which what this does is you know if you look at this doc string this has
some special characters like this. Backslash n and what backslash n does it
normally creates a break line when you when you're inside string, so as you see
when you pass backslash n that will create a break line or like that.
We'll use backslash n later, so don't focus on that for now if you don't understand it.
You'll understand it very well when we use it in real-world examples, so if you
think you're having such special characters, is good to pass r there
and that will treat the string as a raw string, so it will ignore
such characters, so it will not treat backslash n as a special command
for break lines, but it was treated as a single character, so it will print it along
with your line as backslash n. And yeah, that is clear I believe and we close
this lecture now, we have some more lectures to go, so let's move on.