<\/td><\/tr><\/table><\/p>\nAnd so we come to the end of the Office document<\/a> that describes the internal coding conventions of id Software. This last section is pretty non-controversial and so I don’t have a lot to say about it. But here are the last of my notes, for what it’s worth…<\/p>\n As before, the style guide is in bold, and everything else is me blathering.<\/p>\n Variable names start with a lower case character. In multi-word variable names the first word starts with a lower case character and each successive word starts with an upper case.<\/strong><\/p>\n Another holy war topic. How do we name our variables?<\/em> There are a lot of systems. <\/p>\n For years, I heard about, encountered, and put up with “Hungarian” notation. That’s a system where you begin you variable names with a letter to indicate what kind of variable it is:<\/p>\n <\/p>\n I never liked this, and I dismissed it as superfluous, overly verbose, and annoying to type. I went around saying things like, “Hungarian Notation is superfluous, overly verbose, and annoying to type. Also it sucks.” The irony is that I’ve actually been using Hungarian notation this whole time without knowing it.<\/p>\n What I didn’t learn until I began this series is that this is not how Hungarian Notation was supposed to work. This is a misunderstood, bastardized offshoot of the original system<\/a>. This notation scheme is properly called “Systems Hungarian”.<\/p>\n Actual Hungarian Notation – that is, the system devised by the man from Hungary<\/a> himself – was intended to be a system where the first few letters would describe, roughly, how a variable is used or perhaps in what context.<\/p>\n For an example that applies to me: I often find myself working with a lot of different coordinate systems. There are local coordinates. (Steve’s gun model is attached to the hand of his character, which is 0.1 units from his center.) There are global coordinates. (Steve is standing 10m north, 103m west of the world origin.) And screen coordinates. (Steve’s health bar is drawn 5 pixels from the left edge of the screen.)<\/p>\n I’ll be dealing with a lot of X, Y, and Z variables, each of them mapped to a particular coordinate system. If I get confused about what kind I’m dealing with, I’ll end up accidentally attaching Steve’s gun to the world origin instead of his hand, or something similarly absurd. So if I see a variable named “x” in the code, I have to wonder which coordinate system it’s in. To figure it out, I sometimes have to backtrack and read a bunch of code. This sort of review is time consuming and cuts down on the time you’ll be able to spend on more important things, like arguing over brace positioning and tab sizes. <\/p>\n The solution here is to come up with a naming system that lets you know how a variable is being used. Perhaps localX, worldX<\/tt>, or screenX<\/tt>. <\/p>\n I actually began doing this on my own during Project Frontier<\/a>. Although, you can find many spots in the source where I didn’t follow this because I forgot or because the code was borrowed from an older project. When Project Octant<\/a> came along I was a little more careful about it. I’m pretty sure all of my new code follows this, and the only places where I should see unadorned X and Y values is in legacy code.<\/p>\n It seems to be paying off. I’ve run into a few situations where the variable name rescued me from a bit of confusion or foolishness. <\/p>\n This way of naming things is now called “Apps Hungarian”. I’m going to be more intentional about following it in the future. (Systems Hungarian still sucks.)<\/p>\n This goes to show that it’s sometimes worth reading some of those obscure, jargon-laden, theory-heavy essays on coding. Usually I’d rather write<\/em> code than follow long debates about<\/em> code, but I could probably stand to pay a bit more attention to theory. <\/p>\n Defined names use all upper case characters. Multiple words are separated with an underscore.<\/strong><\/p>\n I’ve read my share of code in my lifetime. Code from big companies. Code from small contractors. Code by old timers. Code by college pups. Production code, beta code, prototype code, example code, and legacy code. And I’ve never seen a codebase where anyone deviated from this rule. This rule is so common and so universal that it feels like part of the language itself.<\/p>\n (Okay, there’s a debate over using consts or #defines. The id doc doesn’t get into that, and we already did a few laps around that particular mulberry bush the other day. Let’s just assume we’re talking about consts OR #defines, whichever tickles your particular fancy.)<\/p>\n When you’re coding, you will often need magic numbers. Sure, most of us can recognize the usual suspects like pi, but less famous numbers like 0.017453292 (the number you multiply by to convert degrees into radians) are harder to spot. Your code is going to need a lot of very specific numbers. The number of milliseconds in a minute. Falling acceleration and terminal velocity in Earth gravity. The number of rounds you can put in a revolver. The aspect ratio of a movie screen. The point size of the default font. Whatever. <\/p>\n You can just stick the numbers in your code as literals if you want to make people crazy.<\/p>\n You can tell what this code does, but the magic numbers make it a little harder to sort out. By using #defines <\/p>\n Now we can see what that number 768 is all about. That's how tall the player is. Now we can see that you take 14 points of damage for every body length you fall. Even better, if you need to change something later - like perhaps someone says the player should be 640 units tall instead of 768 - you'll just need to change it in one place. Contrast this with the the first case, where you would need to change all instances of 768 to the new value. If you miss some, then you'll have this strange bug where the game has differing ideas about how tall you are based on what it's doing. Sure, you can use find & replace, but just wait until you have two magic numbers with the same value. Congratulations, you just made the player shorter but also changed the number of bullets they can carry from 768 to 640. Oops.<\/p>\n Having words in ALL_CAPS with underscores is almost universally understood to mean \"this is a #defined value\". Seeing this spelled out in the id Software guide is like seeing a \"All employees must wash hands before returning to work\" sign in the scrub room where everyone gets ready for surgery. Yes, I would hope this is the case, but I'm kind of alarmed that it needed to be said.<\/em><\/p>\n So that's the guide. I'll say that the document strikes me as being very general, brief, and relaxed. I've seen longer and much pickier guides at smaller companies. Then again, I've never worked anywhere that could boast of having id Software-level employees. I suppose in a place like that they can give the programmers more liberty. After all, the rules are supposed to guide you, not hamstring you.<\/p>\n I'm guessing that these style guides are also more detailed when they come from larger companies. (I'll bet Microsoft has many guides that approach novella size.) The larger your team, the more important it is to enforce a rigorous system. Two programmers can quickly learn to spot and accept each other's eccentricities and habits. On a twenty person team, all those little \"personal touches\" can seem like chaos. <\/p>\n","protected":false},"excerpt":{"rendered":" And so we come to the end of the Office document that describes the internal coding conventions of id Software. This last section is pretty non-controversial and so I don’t have a lot to say about it. But here are the last of my notes, for what it’s worth… As before, the style guide is […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[66],"tags":[],"class_list":["post-18500","post","type-post","status-publish","format-standard","hentry","category-programming"],"_links":{"self":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts\/18500","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=18500"}],"version-history":[{"count":0,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts\/18500\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=18500"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=18500"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=18500"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}\r\nfloat x;\r\nfloat maxDistanceFromPlane;\r\n<\/pre>\n
\r\nfHealth = 0.0f; \/\/A float\r\niHealth = 0; \/\/ An integer\r\nszHealth = \"Dead\"; \/\/A string\r\n<\/pre>\n
<\/td><\/tr><\/table><\/p>\n\r\n\r\nif (drop_distance > 768) {\r\n damage = 14 * (drop_distance \/ 768);\r\n if (armor > 0) \r\n damage *= 0.5f;\r\n health -= damage;\r\n if (health <= 0)\r\n GameOver ();\r\n}\r\n<\/pre>\n\r\n#define PLAYER_HEIGHT 768\r\n#define FALLING_DAMAGE 14\r\n#define ARMOR_PROTECTION 0.5f\r\n\r\nif (drop_distance > PLAYER_HEIGHT) {\r\n damage = FALLING_DAMAGE * (drop_distance \/ PLAYER_HEIGHT);\r\n if (armor > 0) \r\n damage *= ARMOR_PROTECTION;\r\n health -= damage;\r\n if (health <= 0)\r\n GameOver ();\r\n}\r\n\r\n<\/pre>\nWrapping Up<\/h3>\n