The tome of wise practices
Some tips on improving code readability.
The Code header
Where the purpose, the author, and the date of creation are inscribed
The header, ahh.. the header. That little snippet of code at the top of the script is like a preamble, a clearing of the throat before the real business begins. What purpose does it serve? Well, the header is a kind of introduction, letting the reader know what's to come with some basic information.
A main() function
Let the Code be governed by a singular, mighty function
Ah, the main() function - now there's a topic! It's like the heart and soul of your code, the place where everything comes together. See, when you're working on a code project, it's like you're building a big machine, right? And the main() function, well, that's the control panel, the place where you pull all the levers and push all the buttons to make the whole thing rock. In order to use that machine, you gotta follow a certain set of steps right? Turn the key, check the fuel, prime the pump.. Well, that's what the main() function is all about - it's the sequence of events that gets your code up and running.
The parameters, guardians of function
Each one a gatekeeper, ensuring the proper flow of information.
Parameters are those little vessels that carry the lifeblood of our functions.
Classes or variables?
Now, I know what you're thinkin' - "But George, how do I know which one to use?" Well, my friend, it all comes down to the task at hand.
If you're dealing with a relatively simple setup like here, them variables-as-parameters might be just the ticket you need. But if you're working on somethin' a little more complex, with all sorts of moving parts and interdependencies, well, them classes, they're the way to go. Classes, are the real MVPs of the bunch, and they will help keeping everything organized and running smooth as silk.
The docstrings, the illuminating scrolls
Where the function's purpose, its workings, and its returns are documented.
Alright, people, let me tell you about these things called docstrings. Now, I know what you're thinking - "Docstrings? What in the Sam Hill are those?" Let me break it down for you.
These docstrings, they're like little notes, little snippets of information that you tack on to your code, just to give folks a heads up on what's going on. It's like when you're doing some work around the house, and you leave a little note for the neighbour, just to let ‘em know what you're up to.
Now, these docstrings, they come in all shapes and sizes. But the way I see it, these docstrings, they're not just about the code, no sir. They're about the people too. So, when you write one of these things, you're not just explaining what the code does, you're telling a story. You're givin' people a little glimpse into your mind and your thought process. And this makes t-h-e difference because on bigger projects, we all know you will never code alone.
Type hints as vigilant sentinels
Ensuring the integrity of the data.
Listen up, I'm about to let you in on a little secret when it comes to this Python business. It's all about them type hints, they're guardrails that keep you from taking a wrong turn by telling your fellow programmers, "hey, this is what I'm expecting here, so don't go messing it up, y'hear?"
See, these type hints, they're some kind of guardians of your program, keeping a watchful eye to make sure you don't go trying to mix apples and oranges, so to speak. When you're dealing with a language as flexible as Python, that's a darn good thing to have in your corner. The more you use ‘em, the more you'll see just how powerful they can be.
If you skipped the project introduction, feel free to check the first chapter (setup), the Code overview, or just dive deep into the source code in the previous chapter!
The code is available on Github.
(Cover picture: unknown).
Top comments (0)