code-es - Tumblr blog

code-es · 11 months ago

Text

How To Make Your Code Actually Good

This is about programming structure and organization. Resources online are very sparse, and usually not super helpful. Which was unhelpful to me who was struggling with code organization.

So I wanted to make this, which will explain how best to structure your code based on what I've learned. What I lay out here may not work for everyone but it works well in my experience.

These resources were very helpful for me

Handmade Hero - https://youtu.be/rPJfadFSCyQ

Entity Component System by The Cherno - https://youtu.be/Z-CILn2w9K0

Game Programming Patterns - https://gameprogrammingpatterns.com/

So, let's get started.

So first we need to cover a few terms. These are Decoupling, and Abstraction.

Decoupling

So, when we code there is only so much information we can keep inside of our brain at one time. If we kept all of our code in a single file, we would have to keep in mind every single line of code we have written thus far. Or, more likely, we would actively ignore certain lines that aren't relevant to whichever problem we are trying to solve. And miss possible errors by skipping over lines we didn't know were important.

This is bad, what we need to do is decouple our code. Decoupling just means to break something up.

We need to split our code into smaller more manageable pieces so that we can focus better on it without cluttering up our brain with useless information.

For example lets take into account a basic game loop

int main(){

bool running = true;

// Game init code

while(running){

// Game update code

}

// Game exit code

return 0;

}

Obviously in a real example this would be much larger. So an extremely good start would be moving chunks of code into different functions.

int main(){

bool running = true;

gameInit();

while(running){

gameUpdate();

}

gameExit();

}

Now, when we are working on loading the game, we shouldn't have to think about what's happening in the rest of the app. This may take moving some code around inorder to truly seperate it from the rest of the code. But it is a very worthwhile effort.

Abstraction

Abstraction is when we take complex pieces of code and put them inside of a function or structure to make that feature easier to use. Or to hide tiny details that would be a waste of time to type out over and over.

For example programming languages are abstracted away from Assembly. Which of course is a thin abstraction away from machine code.

Now abstraction is great, computer science is practically built ontop of abstracting away small details. but the point I'd like to make here is that you can go too crazy with abstraction.

If you are making a gui application, and you need to create a new button. And to do so you need to run a function that returns a new class that you pass into another function that returns a pointer to an app state that you use with the original class to interact with a gui state that takes in a general state class and a position.

You have abstracted too far away to actually getting that button on screen. And due to all the hoops your code has to go through you will face major performance hits as well. And nobody likes a slow program.

Generally my rule of thumb is one layer of abstraction. Obviously for really complex stuff like graphics more abstraction is required. But for our own apps we should strive to as little abstraction as possible. Which makes code more clear and easier to debug, if a little more verbose at times.

Note that breaking things up into other files and functions are pretty cheap abstraction/performance wise. But the number of steps your code has to go through is what's important. Like the number of objects you have to go through, and functions you have to run.

Now these are good general tips for programming. There are also other good tips like consistent naming conventions, and consistent function names and argument patterns. But that's all pretty basic good-programming-things-you-should-do.

Now when I was learning this sort of stuff, I got told a lot of the stuff I just put above. But the biggest question I had was "but where do I PUT all of my code?"

As projects grow in complexity, figuring out sane ways to organize your structures and code logic in a way that makes sense is pretty tricky.

So to kinda crystallize how I think about code organization is basically.

Pick a pattern, and stick to it

A design pattern is just a piece of code structure you repeat. And there are lots of smart people that have come up with some pretty smart and flexible patterns. Like entity component systems, and state machines.

But sometimes you have to figure out your own, or modify existing patterns. And the best way to do that is to not plan at all and jump right in.

Do a rough draft of your app just to get a general idea of what you are going to need your pattern to support. And you may have to build up a pattern, find out it sucks, and start over. The trick is to fail fast and fail often.

Grabbing some paper and trying to diagram out how you want your app to flow is also handy. But getting your hands dirty with your keyboard is the best.

Now if you are new to programming, the above method probably wont work the first time. The only way to really learn code architecture is by building apps, and when you are first starting out many of your apps are probably falling apart early on. But the more you build these apps the more you learn. The bigger the apps you make, the more you learn.

But there is something that's also very helpful.

Steal somebody else's pattern!

So I can explain this best with an example. I make games, and the complexity I have to deal with is having multiple game objects that can all interact with each other fluidly. Enemies, the player, collectibles, moving platforms. This is a pretty tricky task, and I wound up picking two patterns to follow.

The first one is a modified version of a State Machine that I call a Scene Manager.

A scene is essentially a structure that contains an init, update, and exit function and can store data relating to the scene. And I have a Scene Manager that I can dynamically load and unload scenes with. So if I need to create a main menu or a pause menu it's as easy as loading a scene.

For my actual game scene I chose to use an Entity Component System. I linked a video above that explains it very well. To summarize, an ECS use entities. Entities can contain data called components. And systems will grab any entity that has the required components and will modify that entity. For example a Move system will operate on any entities that have the Position and Velocity components.

And this has worked very well for my game. Now this doesnt solve every problem I had. I still had to fill in the gaps with code that doesnt 100% match the pattern. After all there isnt any pattern that will fix all possible issues a codebase needs to solve. For example to delete an entity I have to add it by reference to an array where it is deleted AFTER the game is done updating.

Elsewhere I used a bit of abstraction to make creating entities easier. For example i created a class that stores methods to create entities. Whereas before I was manually adding components to empty structures.

Decoupling entity creation meant I could focus on more important things. I also deal with window resizing and rendering in a layer outside of the scene. In a way that would affect all Scenes.

An Example

In the game I'm making, the most complex part of the program so far is the player update code. Which makes sense for a platformer. So the issue is simple, it's getting too long. But the other issue is things are in places that don't immediately make sense. And it's all packed inside a single function.

You can view the code as it is now here.

Our goal is to decouple the code into pieces so that it takes up less brain space. And to reorganize the function so it's layout makes more immediate sense.

So my first step is to figure out a logical way to organize all of this code. My plan is to split it up by player actions. This way all of the jump logic is inside it's own function. All of the shooting logic is in it's own function etc.

Here is the code after implimenting the pattern.

Notice how this decouples the code into more manageable pieces so we can work on it better. Also note how I am still keeping one layer of abstraction from the player update code. I also put it in a seperate file to slim down the systems file.

So the method I implemented here of observing a problem, coming up with a pattern, and implementing it. That at a larger scale is how to overall structure a good code base. Here in this small instance I found a working solution first try. But for more complex code you may have to try multiple different patterns and solutions before you find what works best.

And that's all I have to say. I hope it made sense, and I hope it helps you. Let me know if I should change anything. Thanks for reading!

#progblr

297 notes · View notes

code-es · 1 year ago

Text

How a Computer Works - Part 1 (Components)

I am about to teach you on a real fundamental, connecting up electronic components level, how a computer actually works. Before I get into the meat of this though (you can just skip down below the fold if you don't care), here's the reasons I'm sitting doing so in this format:

Like a decade or two ago, companies Facebook pushed this whole "pivot to video" idea on the whole internet with some completely faked data, convincing everyone that everything had to be a video, and we need to start pushing back against that. Especially for stuff like complex explanations of things or instructions, it's much more efficient to just explain things clearly in text, maybe with some visual aids, so people can easily search, scan, and skip around between sections. It's also a hell of a lot easier to host things long term, and you can even print out a text based explainer and not need a computer to read it, keep it on a desk, highlight it, etc.

People are so clueless about how computers actually work that they start really thinking like it's all magical. Even programmers. Aside from how proper knowledge lets you get more out of them, this leads to people spouting off total nonsense about "teaching sand to think" or "everything is just 1s and 0s" or "this 'AI' a con artist who was trying to sell me NFTs a month ago probably really is an amazing creative thinking machine that can do everything he says!"

We used to have this cultural value going where it was expected that if you owned something and used it day to day, you'd have enough basic knowledge of how it worked that if it stopped working you could open it up, see what was wrong, and maybe fix it on your own, or maybe even put one together again from scratch, and that's obviously worth bringing back.

I'm personally working on a totally bonkers DIY project and I'd like to hype up like-minded people for when it gets farther along.

So all that said, have a standard reminder that I am completely reliant on Patreon donations to survive, keep updating this blog, and ideally start getting some PCBs and chips and a nice oscilloscope to get that mystery project off the ground.

Electricity probably doesn't work like how you were taught (and my explanation shouldn't be trusted too far either).

I remember, growing up, hearing all sorts of things about electricity having this sort of magical ability to always find the shortest possible path to where it needs to get, flowing like water, and a bunch of other things that are kind of useful for explaining how a Faraday cage or a lightning rod works, and not conflicting with how simple electronics will have a battery and then a single line of wire going through like a switch and a light bulb or whatever back to the other end of the battery.

If you had this idea drilled into your head hard enough, you might end up thinking that if we have a wire hooked to the negative end of a battery stretching off to the east, and another wire stretching off to the east from the positive end, and we bridge between the two in several places with an LED or something soldered to both ends, only the westernmost one is going to light up, because hey, the shortest path is the one that turns off as quickly as possible to connect to the other side, right? Well turns out no, all three are going to light up, because that "shortest path" thing is a total misunderstanding.

Here's how it actually works, roughly. If you took basic high school chemistry, you learned about how the periodic table is set up, right? A given atom, normally, has whatever number of protons in the core, and the same number of electrons, whipping all over around it, being attracted to those protons but repelled by each other, and there's particular counts of electrons which are super chill with that arrangement so we put those elements in the same column as each other, and then as you count up from those, you get the elements between those either have some electrons that don't fit all tight packed in the tight orbit and just kinda hang out all wide and lonely and "want to" buddy up with another atom that has more room, up to the half full column that can kinda go either way, then as we approach the next happy number they "want to" have a little more company to get right to that cozy tight packed number, and when you have "extra" electrons and "missing" electrons other atoms kinda cozy up and share so they hit those good noble gas counts.

I'm sure real experts want to scream at me for both that and this, but this is basically how electricity works. You have a big pile of something at the "positive" end that's "missing electrons" (for the above reason or maybe actually ionized so they really aren't there), and a "negative" end that's got spares. Then you make wires out of stuff from those middle of the road elements that have awkward electron counts and don't mind buddying up (and also high melting points and some other handy qualities) and you hook those in there. And the electron clouds on all the atoms in the wire get kinda pulled towards the positive side because there's more room over there, but if they full on leave their nucleus needs more electron pals, so yeah neighbors get pulled over, and the whole wire connected to the positive bit ends up with a positive charge to it, and the whole wire on the negative bit is negatively charged, and so yeah, anywhere you bridge the gap between the two, the electrons are pretty stoked about balancing out these two big awkward compromises and they'll start conga lining over to balance things out, and while they're at it they'll light up lights or shake speakers or spin motors or activate electromagnets or whatever other rad things you've worked out how to make happen with a live electric current.

Insulators, Resistors, Waves, and Capacitors

Oh and we typically surround these wires made of things that are super happy about sharing electrons around with materials that are very much "I'm good, thanks," but this isn't an all or nothing system and there's stuff you can connect between the positive and negative ends of things that still pass the current along, but only so much so fast. We use those to make resistors, and those are handy because sometimes you don't want to put all the juice you have through something because it would damage it, and having a resistor anywhere along a path you're putting current through puts a cap on that flow, and also sometimes you might want a wire connected to positive or negative with a really strong resistor so it'll have SOME sort of default charge, but if we get a free(r) flowing connection attached to that wire somewhere else that opens sometimes, screw that little trickle going one way, we're leaning everyone the other way for now.

The other thing with electricity is is that the flow here isn't a basic yes/no thing. How enthusiastically those electrons are getting pulled depends on the difference in charge at the positive and negative ends, and also if you're running super long wires then even if they conduct real good, having all that space to spread along is going to kinda slow things to a trickle, AND the whole thing is kinda going to have some inherent bounciness to it both because we're dealing with electrons whipping and spinning all over and because, since it's a property that's actually useful for a lot of things we do with electricity, the power coming out of the wall has this intentional wobbly nature because we've actually got this ridiculous spinny thing going on that's constantly flip flopping which prong of the socket is positive and which is negative and point is we get these sine waves of strength by default, and they kinda flop over if we're going really far.

Of course there's also a lot of times when you really want to not have your current flow flickering on and off all the time, but hey fortunately one of the first neat little electronic components we ever worked out are capacitors... and look, I'm going to be straight with you. I don't really get capacitors, but the basic idea is you've got two wires that go to big wide plates, and between those you have something that doesn't conduct the electricity normally, but they're so close the electromagnetic fields are like vibing, and then if you disconnect them from the flow they were almost conducting and/or they get charged to their limit, they just can't deal with being so charged up and they'll bridge their own gap and let it out. So basically you give them electricity to hold onto for a bit then pass along, and various sizes of them are super handy if you want to have a delay between throwing a switch and having things start doing their thing, or keeping stuff going after you break a connection, or you make a little branching path where one branch connects all regular and the other goes through a capacitor, and the electricity which is coming in in little pulses effectively comes out as a relatively steady stream because every time it'd cut out the capacity lets its charge go.

We don't just have switches, we have potentiometers.

OK, so... all of the above is just sort of about having a current and maybe worrying about how strong it is, but other than explaining how you can just kinda have main power rails running all over, and just hook stuff across them all willy-nilly rather than being forced to put everything in one big line, but still, all you can do with that is turn the whole thing on and off by breaking the circuit. Incidentally, switches, buttons, keys, and anything else you use to control the behavior of any electronic device really are just physically touching loose wires together or pulling them apart... well wait no, not all, this is a good bit to know.

None of this is actually pass/fail, really, there's wave amplitudes and how big a difference we have between the all. So when you have like, a volume knob, that's a potentiometer, which is a simple little thing where you've got your wire, it's going through a resistor, and then we have another wire we're scraping back and forth along the resistor, using a knob, usually, and the idea is the current only has to go through X percent of the resistor to get to the wire you're moving, which proportionately reduces the resistance. So you have like a 20 volt current, you've got a resistor that'll drop that down to 5 or so, but then you move this other wire down along and you've got this whole dynamic range and you can fine tune it to 15 or 10 or whatever coming down that wire. And what's nice about this again, what's actually coming down the wire is this wobbily wave of current, it's not really just "on" or "off, and as you add resistance, the wobble stays the same, it's just the peaks and valleys get closer to being just flat. Which is great if you're making, say, a knob to control volume, or brightness, or anything you want variable intensity in really.

Hey hey, it's a relay!

Again, a lot of the earliest stuff people did with electronics was really dependent on that analog wobbly waveform angle. Particularly for reproducing sound, and particularly the signals of a telegraph. Those had to travel down wires for absurd distances, and as previously stated, when you do that the signal is going to eventually decay to nothing. But then someone came up with this really basic idea where every so often along those super long wires, you set something up that takes the old signal and uses it to start a new one. They called them relays, because you know, it's like a relay race.

If you know how an electromagnet works (something about the field generated when you coil a bunch of copper wire around an iron core and run an electric current through it), a relay is super simple. You've got an electromagnet in the first circuit you're running, presumably right by where it's going to hit the big charged endpoint, and that magnetically pulls a tab of metal that's acting as a switch on a new circuit. As long as you've got enough juice left to activate the magnet, you slam that switch and voom you've got all the voltage you can generate on the new line.

Relays don't get used too much in other stuff, being unpopular at the time for not being all analog and wobbily (slamming that switch back and forth IS going to be a very binary on or off sorta thing), and they make this loud clacking noise that's actually just super cool to hear in devices that do use them (pinball machines are one of the main surviving use cases I believe) but could be annoying in some cases. What's also neat is that they're a logical AND gate. That is, if you have current flowing into the magnet, AND you have current flowing into the new wire up to the switch, you have it flowing out through the far side of the switch, but if either of those isn't true, nothing happens. Logic gates, to get ahead of myself a bit, are kinda the whole thing with computers, but we still need the rest of them. So for these purposes, relays re only neat if it's the most power and space efficient AND gate you have access to.

Oh and come to think of it, there's no reason we need to have that magnet closing the circuit when it's doing its thing. We could have it closed by default and yank it open by the magnet. Hey, now we're inverting whatever we're getting on the first wire! Neat!

Relay computers clack too loud! Gimme vacuum tubes!

So... let's take a look at the other main thing people used electricity for before coming up with the whole computer thing, our old friend the light bulb! Now I already touched a bit on the whole wacky alternating current thing, and I think this is actually one of the cases that eventually lead to it being adopted so widely, but the earliest light bulbs tended to just use normal direct current, where again, you've got the positive end and the negative end, and we just take a little filament of whatever we have handy that glows when you run enough of a current through it, and we put that in a big glass bulb and pump out all the air we can, because if we don't, the oxygen in there is probably going to change that from glowing a bit to straight up catching on fire and burning immediately.

But, we have a new weird little problem, because of the physics behind that glowing. Making something hot, on a molecular level, is just kinda adding energy to the system so everything jitters around more violently, and if you get something hot enough that it glows, you're getting it all twitchy enough for tinier particles to just fly the hell off it. Specifically photons, that's the light bit, but also hey, remember, electrons are just kinda free moving and whipping all over looking for their naked proton pals... and hey, inside this big glass bulb, we've got that other end of the wire with the more positive charge to it. Why bother wandering up this whole coily filament when we're in a vacuum and there's nothing to get in the way if we just leap straight over that gap? So... they do that, and they're coming in fast and on elliptical approaches and all, so a bunch of electrons overshoot and smack into the glass on the far side, and now one side of every light bulb is getting all gross and burnt from that and turning all brown and we can't have that.

So again, part of the fix is we switched to alternating current so it's at least splitting those wild jumps up to either side, but before that, someone tried to solve this by just... kinda putting a backboard in there. Stick a big metal plate on the end of another wire in the bulb connected to a positive charge, and now OK, all those maverick electrons smack into here and aren't messing up the glass, but also hey, this is a neat little thing. Those electrons are making that hop because they're all hot and bothered. If we're not heating up the plate they're jumping to, and there's no real reason we'd want to, then if we had a negative signal over on that side... nothing would happen. Electrons aren't getting all antsy and jumping back.

So now we have a diode! The name comes because we have two (di-) electrodes (-ode) we care about in the bulb (we're just kind of ignoring the negative one), and it's a one way street for our circuit. That's useful for a lot of stuff, like not having electricity flow backwards through complex systems and mess things up, converting AC to DC (when it flips, current won't flow through the diode so we lop off the bottom of the wave, and hey, we can do that thing with capacitors to release their current during those cutoffs, and if we're clever we can get a pretty steady high).

More electrodes! More electrodes!

So a bit after someone worked out this whole vacuum tube diode thing, someone went hey, what if it was a triode? So, let's stick another electrode in there, and this one just kinda curves around in the middle, just kinda making a grate or a mesh grid, between our hot always flowing filament and that catch plate we're keeping positively charged when it's doing stuff. Well this works in a neat way. If there's a negative charge on it, it's going to be pushing back on those electrons jumping over, and if there's a positive charge on it, it's going to help pull those electrons over (it's all thin, so they're going to shoot right past it, especially if there's way more of a positive charge over on the plate... and here's the super cool part- This is an analog thing. If we have a relatively big negative charge, it's going to repel everything, if it's a relatively big positive, it's going to pull a ton across, if it's right in the middle, it's like it wasn't even in there, and you can have tiny charges for all the gradients in between.

We don't need a huge charge for any of this though, because we're just helping or hindering the big jump from the high voltage stuff, and huh, weren't we doing this whole weak current controlling a strong current thing before with the relay? We were! And this is doing the same thing! Except now we're doing it all analog style, not slapping switch with a magnet, and we can make those wavy currents peak higher or lower and cool, now we can have phone lines boost over long distances too, and make volume knobs, and all that good stuff.

The relay version of this had that cool trick though where you could flip the output. Can we still flip the output? We sure can, we just need some other toys in the mix. See we keep talking about positive charges and negative charges at the ends of our circuits, but these are relative things. I mentioned way back when how you can use resistors to throttle how much of a current we've got, so you can run two wires to that grid in the triode. One connects to a negative charge and the other positive, with resistors on both those lines, and a switch that can break the connection on the positive end. If the positive is disconnected, we've got a negative charge on the grid, since it's all we've got, but if we connect it, and the resistor to the negative end really limits flow, we're positive in the section the grid's in. And over on the side with the collecting plate, we branch off with another resistor setup so the negative charge on that side is normally the only viable connection for a positive, but when we flip the grid to positive, we're jumping across the gap in the vacuum tube, and that's a big open flow so we'll just take those electrons instead of the ones that have to squeeze through a tight resistor to get there.

That explanation is probably a bit hard to follow because I'm over here trying to explain it based on how the electrons are actually getting pulled around. In the world of electronics everyone decided to just pretend the flow is going the other way because it makes stuff easier to follow. So pretend we have magical positrons that go the other way and if they have nothing better to do they go down the path where we have all the fun stuff further down the circuit lighting lights and all that even though it's a tight squeeze through a resistor, because there's a yucky double negative in the triode and that's worse, but we have the switch rigged up to make that a nice positive go signal to the resistance free promised land with a bonus booster to cut across, so we're just gonna go that way when the grid signal's connected.

Oh and you can make other sorts of logic circuits or double up on them in a single tube if you add more grids and such, which we did for a while, but not really relevant these days.

Cool history lesson but I know there's no relays or vacuum tubes in my computer.

Right, so the above things are how we used to make computers, but they were super bulky, and you'd have to deal with how relays are super loud and kinda slow, and vacuum tubes need a big power draw and get hot. What we use instead of either of those these days are transistors. See after spending a good number of years working out all this circuit flow stuff with vacuum tubes we eventually focused on how the real important thing in all of this is how with the right materials you can make a little juncture where current flows between a positive and negative charge if a third wire going in there is also positively charged, but if it's negatively charged we're pulling over. And turns out there is a WAY more efficient way of doing that if you take a chunk of good ol' middle of the electron road silicon, and just kinda lightly paint the side of it with just the tiniest amount of positive leaning and negative leaning elements on the sides.

Really transistors don't require understanding anything new past the large number of topics already covered here, they're just more compact about it. Positive leaning bit, negative leaning bit, wildcard in the middle, like a vacuum tube. Based on the concepts of pulling electrons around from chemistry, like a circuit in general. The control wire in the middle kinda works in just a pass-fail sort of way, like a relay. They're just really nice compared to the older alternatives because they don't make noise or have moving parts to wear down, you don't have to run enough current through them for metal to start glowing and the whole room to heat up, and you can make them small. Absurdly small. Like... need an electron microscope to see them small.

And of course you can also make an inverter super tiny like that, and a diode (while you're at it you can use special materials or phosphors to make them light emitting, go LEDs!) and resistors can get pretty damn small if you just use less of a more resistant material, capacitors I think have a limit to how tiny you can get, practically, but yeah, you now know enough of the basic fundamentals of how computers work to throw some logic gates together. We've covered how a relay, triode, or transistor function as an AND gate. An OR gate is super easy, you just stick diodes on two wires so you don't have messy backflow then connect them together and lead off there. If you can get your head around wiring up an inverter (AKA NOT), hey, stick one after an AND to get a NAND, or an OR to get a NOR. You can work out XOR and XNOR from there right? Just build 4 NANDs, pass input A into gates 1 and 2, B into 2 and 3, 2's output into 1 and 3, 1 and 3's output into 4 for a XOR, use NORs instead for a XNOR. That's all of them right? So now just build a ton of those and arrange them into a computer. It's all logic and math from there.

Oh right. It's... an absurd amount of logic and math, and I can only fit so many words in a blog post. So we'll have to go all...

CONTINUED IN PART 2!

Meanwhile, again, if you can spare some cash I'd really appreciate it.

#computer science #computers

552 notes · View notes