Write Pythonic Code Like a Seasoned Developer Transcripts
Chapter: Style guidance from PEP 8
Lecture: Naming conventions
0:01 Let's talk about naming conventions.
0:03 PEP 8 actually says a lot about how you should name
0:05 your functions, methods, classes, and other symbols in your code.
0:08 Before we get to the specifics,
0:11 I just want to give you one of my core programming guidelines around naming,
0:14 and that is names should be descriptive.
0:17 Let's imagine you are writing a function.
0:19 If you write the function and then you start to put a comment
0:22 at the top to describe what that function does,
0:24 I encourage you to stop and think about just making the concise statement
0:29 about what that comment is the name of the function.
0:32 I am a big fan of Martin Fowler's Reafctoring ideas
0:35 and especially the code smells that he talks about,
0:38 and code smells are things in code that are not really broken
0:41 but they kind of smell off, like a function that is 200 lines long,
0:47 it's not broken, it just doesn't seem right.
0:50 It sort of smells wrong, right, so breaking that
0:53 to a smaller bunch of functions through refactoring might be the solution.
0:57 And when he talks about comments he says
0:59 comments are deodorant for code smell,
1:01 instead of actually fixing the code
1:04 so it's remarkably descriptive and easy to understand,
1:06 people often put comments to say here is this really hard to understand thing,
1:10 and here is the comment that says why it's this way
1:13 or what it actually does or maybe in my mind,
1:15 what it really should be named.
1:17 So my rule of thumb is if you need a comment
1:19 to describe what a function does, you probably need a better name.
1:22 That said, let's talk about how PEP 8 works.
1:24 So here is some code that is PEP 8 compliant.
1:26 We have a module called data_access and modules should all have short,
1:31 all lower case names and if needed for readability
1:35 you can put underscore separating them.
1:38 Next you see we have a content that does not change
1:41 during the execution of our code, it's called TRANSACTION_MODE
1:43 and I forced it to be serializable.
1:46 These should be all upper case.
1:48 Classes, classes have cap word names, like this,
1:51 CustomerRepository, capital C capital R.
1:55 Variables and function arguments are always lower case,
1:59 possibly separated with underscores as well;
2:02 functions and methods lower case, again,
2:05 possibly separated with underscores.
2:07 And if you happen to create your own exception type,
2:09 here we might want to raise a RepositoryError and it derives from the exception class,
2:14 when you have exceptions they should always be named in error,
2:18 so something error. Here we have repository error.
2:22 As you have seen in other cases, PyCharm will help us here,
2:28 with the capital M and not the underscore,
2:31 you hover over it PyCharm will say
2:34 no, no, no, you are naming your functions wrong.
2:36 It'll even let us hit alt enter and give us some options about fixing this up,
2:41 it doesn't quite understand how to rename it for us
2:44 but at least it gives us the option to go over here and do a rename.
2:47 Now this is not this renaming in place but this is a refactor rename
2:49 across the entire project, so if we had hundreds of files docstrings,
2:53 that sort of stuff, this would fix all of those.
2:57 It'll show us where it's going to change,
2:59 here we don't have anything going on really so it's just this one line.
3:02 Now, our warning is gone.