[MUSIC] [MUSIC]. In this class, we're going to give you a set of style guidelines, and we're going to expect you to adhere to them. This is important. In any large-scale software development project, there will be a set of style guidelines, and everyone on the team will be expected to follow them. This allows everyone to be able to expect a consistent style throughout the code, without jarring transitions from one programmer to another. Okay, so this is a very important skill for you to acquire. The ability to follow these kinds of style guidelines, okay? And, the problem with this really is that, not everyone really agrees on what the best style is, right? Programmers will never agree on, you know, how to best write a program or how to best structure things, or how or what the best style is, okay? So all style guidelines are necessarily a compromise. Alright, our's here is a compromise between what we think is best. What Python programmers traditionally advocate, and what we think is appropriate for a class of this level. And we found that the style guidelines we're promoting here work well at Rice. And they allow students to understand the underlying principles and concepts of good programming, okay? And that's what we're going for here. Right? It's really about the principles, not the particulars, right? These principles are important, okay? And so look past, sort of, any differences you might have with the style guidelines and think about, what are the underlying concepts that are trying to convey here? One important point, however, is that we will diverge from common Python programming practices in some places. ' Kay, and to them I want to point out, the title of this class is Principles of Computing, not Intermediate Python Programming. So the choices that we've made are designed to allow us to convey these principles better, okay? And so, this is not to say that Python programmers are wrong, or there's something wrong with common Python style. There's not. It's just that we feel that we can better convey some concepts to you with a different style, okay? We will be using Pylint to enforce this style. And there's something very rigid about using a machine to enforce style guidelines. But really, that's the only way to do it in a class of this size. And also Pylint then will give you some help, right, it will tell you when you're violating the style guidelines so that you can see exactly where you violated them. And then be able to go back and fix your code, okay? Now, I want to come back to the point that it's really the principles and concepts that are important here, not the particulars. So I want you to look past these particulars, alright? And think about this as, I'm acquiring a skill in thinking about what these concepts are and why this leads to better programs. Okay, so why do we want to do this? Alright and I already touched upon this a little bit, but I think the major factor here is readability. And it's not just readability for other people. It's for you as well, 'kay? So this is, how do we think about making our programs more readable for both you and other people. Because often the other person looking at your code, is actually, you, alright? But it's not you, like, as you're writing it, it's rather you wrote something, and it was really complex, you're really proud of it, you put it on up on the shelf. And then two months later, or six months later, or a year later you come back and you say, oh I need, I already wrote a piece of code to do that, and you go get it. And you look at it and you're like I have no idea what I was thinking. I don't know what this does, I'm not sure how to use it and so on. Okay? So readability is key. If you follow a consistent set of style guidelines that are geared towards readability this makes this better. Okay? And this not only helps when you dust off an old piece of code. This helps when you show somebody else code, this helps when you try to debug your code. If your code is well and clearly written. And there are errors in it you can find them easier. You can maintain the code easier. When you find that you have to change something because the requirements of the program have evolved over time. And you go back and look at a piece of code you haven't touched for quite a while and you need to change it. If it's well written then, that becomes much easier to do, 'kay? So I think that one of the keys here is that you want to make it, errors more obvious, okay? If you write your code in a structured way. Errors just sort of jump out at you sometimes. Okay, further, you want to make it easier to collaborate so that you, other people can read your code. The errors jump out at them. So maybe if you're asking them to help you that'll be easier for them to help you. Or if they're trying to maintain and, and improve the code. And change, in the face of changing requirements, they can go make modifications to your code without cursing your name, okay? Now, in small programs, in the, you know, 100 or 200 line programs that we're going to write here, well, how important is this? It's unclear, okay? It does help, and it helps a lot, but you're going to be able to get away with not doing it. This is really a practice that you need to get in the habit of, right away, while you're writing small programs. Because when you write bigger programs, it's critical, okay? So you want to do the right thing, even when you're writing small programs, and it doesn't seem necessary. So that when you start writing bigger programs, the habits are already ingrained, and you've already thought about hey, this is how I should approach programming. 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. Coding style matters. It's a part of good programming and it's a part of taking a principled approach to thinking about how you're going to structure code and how you're going to be a computer scientist. Okay? You may not always agree with the style guidelines that are here, okay? But you're never going to agree with any style guidelines anybody writes, unless you write them yourself, okay? And then somebody else is going to disagree with your guidelines. So, let's all just get it out of our system. Damn you, Rixner! 'Kay, fine. You can curse my name every time you don't like it. I, I get it and I understand. But this is a part of sort of working with other people, and taking a principled approach to programming. And I think that it's important, okay? Even if you don't agree with the particular style guidelines here, I ask you to follow them. I ask you to get in the habit of following sty, style guidelines. And understanding why this leads to code that allows you to be, that, that is more readable and maintainable, and allows you to do a better job of communicating what you're trying to do to others.
