>> One of the things that you will very
likely be doing as you continue to
create and build more code is to
maybe update something inside of an open source project.
Or maybe you are now part of a team and you're going to be sharing
your code out with your teammates and so forth.
So as part of that,
you really want to make sure that you play well with others,
so to speak, that you become part of the community
and follow along with some good community standards.
So that's really what we want to talk about here in
our formatting and linting section.
So first up, let's highlight this.
Everything that you see on the screen is in fact valid Python.
All of that will run just fine the way
that it is, no updates needed.
But take a look at that,
It's not really readable code, it's not pleasant.
It's well, quite frankly,
it's annoying, it's clunky.
You're going to notice that we have all various issues,
that we've got inconsistent use of whitespace so
that in certain areas we've got spaces here and here,
but we don't have a space here.
You're going to notice that we've tabbed in to
varying levels here and so forth.
You'll also notice that we've got
inconsistencies when it comes to "things like that."
All of those different odds and ends are things
that can make your code more difficult to maintain,
and they're also going to potentially create
issues when you go to share this code out with your teammates,
other developers, or potentially the community.
So in the end, formatting matters.
That it's going to make your code more readable.
It's going to help everybody else that you're working with,
and it's also going to make it easier to debug.
In all of my time,
one thing that I've noticed that are
constant is the developers that I see that are
struggling the most to fix so many bugs are oftentimes
the same developers who don't spend an awful lot
of time worrying about what their formatting is,
or put another way, don't have consistent formatting.
I'm not quite sure if there's causation or correlation there,
but there's definitely something there.
So formatting does matter.
So taking a little bit of time to make sure that you've made
the decisions about how you want your code
to look is going to help you out.
That honestly, when I'm writing code,
I'm very rarely thinking about how I want to format the code.
The reason for that is,
I've made the decisions on how I want my code to
look so all I'm doing is just executing that plan.
That way when it comes up
where there is maybe a decision to be made,
that maybe I'm calling a function or a method,
and I've got a lot of parameters and
maybe I'm doing a couple of other things as part of that,
and I'm trying to figure out, ''Okay,
well, do I tab into here?
Do I tab into there,'' and so forth.
I can focus in on those decisions when those matter.
More importantly, by having
made my formatting decisions in advance,
it allows me to spend a lot more time focused in on what it is
that I'm building and a lot less
time on how it is that my code is going to look.
Because again, I've already made those decisions.
Now when it comes to Python,
there's this little proposal called PEP 8,
or Python Enhancement Proposal 8 that
is 100 percent about formatting.
If you go check out the Python site,
we'll link to it inside the GitHub,
you're going to notice that it's very
exacting when it comes to formatting in Python.
Now I'm not going to go through
every single rule that makes up PEP 8,
but I do want to highlight a couple of very common ones.
So first step spaces, not tabs.
I'm not going to get into the middle of that debate.
Spaces, not tabs, I will say in Visual Studio code,
when you hit the ''Tab'' button,
it will replace it with spaces so you're good to go there,
but it is spaces not tabs when it comes to Python.
Variable name with underscores,
and not either camel or Pascal cased.
So we want that first one,
not the last two.
You also want to avoid extraneous whitespace.
So what I want you to notice here is we've got
a space there between the colon and the number 42.
That's good because there's no space
right after the word good. That's good.
You're going to notice that we've got a space here,
and a space here that's extraneous whitespace,
or more specifically, it's the space that's right there.
That's the extraneous one.
That's the one that we want to avoid.
Now you're going to notice
again that there's a whole bunch of rules,
and chances are you probably not going to remember all of them.
I'll be honest, I don't.
This is where a tool like linting comes into play.
A linter,
which you're going to notice basically every language has,
is going to be there to help support you
when it comes to all these different types of issues.
So things like naming,
things like spacing, etc.
Now you will need to install a linter,
Pylint by far being the most common,
you'll notice that we can install that just by
using the PEP command,
and then away we go from there.
We are going to see when I get into
the demo here in just a moment,
that this is automatically runnable inside of Visual Studio Code.
I also want to mention the fact that you
can set up a configuration file.
So that way, if maybe there
are certain rules that you want to ignore,
certain rules that you want to add,
that you can go ahead and do that.
You'll even actually notice if you dig deeper into this,
that you can even ignore rules for just one line of code.
I do want to recommend, however,
that you avoid doing that.
The word that we're looking for here is exception.
We're looking to make an exception to the rule.
If we're doing that constantly,
it's now no longer an exception,
it's now just well, the rule.
So if a linter is yelling at you
because you have poorly formatted code,
the suggestion is to make sure that your code
complies with the rule rather than avoiding the rule.
It's just going to make your code, again,
that much more readable,
that much more maintainable.
Speaking of making your code more readable and easier to use,
we have this little thing called a document string or a docstring.
Now what I want you to notice is,
we've used three quotes here.
Three quotes can be used to create
a multi-line string literal inside of Python.
But if you're not, say passing this into
a parameter or setting that to be a variable,
it now becomes what's known as a docstring,
effectively a multi-line comment.
If you put this at the top of a construct,
such as a function in my case,
or maybe a class,
it now becomes a document string.
Now what I want you to notice is the fact
that I've got a little description
of what it is that this is going to do,
I've got a little section for
my parameters where I'm listing off all the parameters.
Then last but not least,
you're going to notice that I've specified the return value.
What's really nice about putting them in a docstring
is when I'm using a tool like Visual Studio Code,
that it's automatically going to then display
this in the IntelliSense as part of my function.
So when I bring up this function,
I'm now going to see that docstring.
It makes it so much easier for somebody
else to use the tools that you've created.
The last little thing that we want to highlight when it comes to
helping out our users is dealing with weakly typed languages.
What you're going to notice there is that that is valid code.
But if we spin this forward,
if we actually ran this,
we're going to wind up getting an error message.
Because we passed an integer,
we tried to add an integer to a string,
Python doesn't really like that.
So what went wrong here is we passed in the wrong data type.
Now we can oftentimes avoid
this or help people avoid this just by using good parameter names.
Let's be honest here, if you see name,
you shouldn't be passing in a number almost always.
Names implies the fact that it's a string.
But what happens if maybe we
don't have a really clear variable name for some reason,
or maybe we also want to be able to indicate
what it is that this function is able to do.
This is where type hints come into play.
Now type hints are relatively new in Python.
You are going to notice that they're not commonly used,
but I'm a huge fan of them,
especially because of the fact that
I also do an awful lot of TypeScript.
If you've done TypeScript,
a lot of this is going to look very familiar.
So what we're going to see here is the fact that we're
now indicating that my name here is going to be a string,
and we're also going to indicate the fact that we're going
to return a string.
Again, when Visual Studio sees this,
when Visual Studio Code sees this,
it's automatically going to pop all of that
up inside of my IntelliSense.
Let's see how we can take advantage of
Visual Studio Code to do linting,
and how we can use both docstrings and type hints to be able
to get a little bit more information
about the functions that we're going to be calling.