So we can't just ask you to guess what
our coding style guidelines are, so we have posted them.
And I'm going to talk about them briefly in here, and give you the highlights.
Okay?
If you go to the course webpage, and you go under, okay, coding notes.
You will be able to find a link
to the coding style guidelines for this class, okay?
And, in this class, we're going to expect you to follow
these, and we're going to enforce them with a program called Pylint.
Alright, and Pylint's going to run with the machine grader and any
style, you know, conventions that are violated, it's going to deduct points.
Okay, alright.
One of the key elements of good style is documentation and comments, okay?
Python has the notion of a doc string.
And you should put doc strings pretty much everywhere.
You document the file, saying what this module is doing.
You document your function, saying what this function is doing.
You document your classes, saying what is this class
doing, and so on, and on and on, okay?
Documentation strings, right, are not telling
you how the code is doing something.
Rather, they're telling you what it is doing, right?
They're saying that this function is computing the square root of n.
Right, it is not telling you how it's doing it.
It's not telling you the specific
algorithm or specific methodology that it's using.
It's just saying, this is what it's doing.
So as a user of that function, I look at
the docstring and I can find out what it does.
And now I know how to use it, right?
And that could mean that it has to explain
in detail what the arguments are supposed to be.
It could have to explain exactly what it's going to
return, and it could explain what it's going to do.
You need to use your discretion in sort of understanding,
you know, what needs to be said so that it is
clear to someone who's trying to use your function or your
class or your module, what that function, class or module does.
Now, you also sometimes have to, you know, describe what the code is doing.
Right?
So comments should be doing that.
That's where comments belong.
They do not belong everywhere, you do not have to document, to
put a comment on absolutely every line of code you ever write.
Rather, you put a comment when the code
might be found confusing, saying that, you know.
I am using the super secret Rixner method for computing the square root
of n and what you have to do is blah, blah, blah, okay?
Now, I've described how its doing it so that someone who comes
back and looks at my code later says hey this looks confusing.
it says, hey, this is how this actual piece of
code is computing whatever it is that it's computing, okay?
And if it's not even obvious what it is computing,
you should put that in the comment as well, alright?
I also want to make a point here, this is one my
personal pet peeves, is that a string is not a comment alright?
A lot of people in Python uses strings as comments.
Well, strings are not comments, okay?
Comments have a little hashtag in front of
the line, strings have quotes around them okay?
If you put quotes around something in Python,
you just say, turn this into a string, okay?
Python evaluates that string as an expression, returns
it, you know you're not doing anything with it.
And it throws it away.
This is a big waste.
Okay, it's not correct.
You should use comments.
Alright, let's talk about variables.
Variables should have meaningful names.
You should not name a variable S.
I have no [LAUGH] idea what that means.
Rather you should name it Result String or something more
useful that explains what the purpose of that variable actually is.
What information is it holding?
Okay?
You should also not have variables that are not used.
Okay?
If you have a variable that was defined to be the number six, and then
nobody ever uses it, I have no idea why you did that or why it's there.
Okay?
You also should not have global variables in your programs.
There's a lot of people that like to have global variables, right?
You should not be one of those people, okay?
Global variables lead, lead, lead to lots of problems in programs, okay?
The only exception in Python is constants.
Python has no notion of an actual constant, so by convention,
constants in Python are global variables with names that are all caps.
So if you see a variable in all caps, that tells
you immediately, this is a constant, you should never change it, okay?
Alright, so, my variables are going to have meaningful names, they're going to be
at least three characters long and they're not going to be global.
We're going to follow similar conventions for classes.
Class names have to also be at least three characters long.
The difference here is that classes should start with an uppercase letter, right?
That allows us to immediately distinguish between a class name and a variable name.
If I see something with an uppercase letter, I know it's a class name.
If I see something that starts with a
lowercase letter, I know it's a variable name, okay?
And this helps make your code more readable, alright.
Now with classes, another big thing, we are not going to use public fields.
We're going to keep our fields hidden, alright?
We're not going to access the internals of a class from outside the class, okay?
And by, in Python there's no way to actually to enforce this restriction.
But by convention, if you name a class field
with a variable name that starts with an underbar.
Okay, that means this is private, don't touch.
Don't look at this, don't, don't do anything with it.
Okay so, we're going to make all of our class fields start with underbars.
We're not going to access them from outside the class.
Now this is not completely Pythonic.
This is one thing where I'm going to diverge a little bit from Python.
Okay, and I want to transcend Python a little bit.
A lot of Python programmers use, you know, public fields, or they use decorators or
other mechanisms inside of Python to allow me to access those internals of the class.
We're going to think a little bit more broadly and say hey, in general,
in object-oriented programming, this is a
bad idea, I want to keep everything hidden.
And I only want to access things in my
class through the methods of that class, okay?
So, we're going to be a little bit more strict
than your typical Python programmer on this point, okay?
But I still think this is important and it's a good habit to get into.
So, this is not an exhaustive list of the style guidelines in this class.
You need to go to that webpage and you need to
look over the style guidelines and make sure you understand them.
Also, the machine grader is going to use Pylint, as
I said, and then Pylint will give you additional errors.
Alright, and when you see these you can go to the web page there's an explanation of
many of the Pylint errors or you can
post in the forums if you don't understand them.
Alright, but you need to conform to those as well.