{"id":48518,"date":"2019-11-14T06:00:12","date_gmt":"2019-11-14T11:00:12","guid":{"rendered":"https:\/\/www.shamusyoung.com\/twentysidedtale\/?p=48518"},"modified":"2019-11-14T09:40:50","modified_gmt":"2019-11-14T14:40:50","slug":"programming-vexations-part-10-header-files","status":"publish","type":"post","link":"https:\/\/www.shamusyoung.com\/twentysidedtale\/?p=48518","title":{"rendered":"Programming Vexations Part 10: Header Files"},"content":{"rendered":"<p>I&#8217;ve talked about C++ header files <a href=\"?p=24516\">before<\/a>. Like I said earlier in this series, the C language was designed in an age where memory was scarce and it wasn&#8217;t feasible for the compiler to hold your entire codebase in memory at once. So projects end up broken up into many different files.<\/p>\n<p>The file marine.c needs to refer to the code in weapons.c, and vehicles.c. Somehow the compiler needs to be aware of the contents of those other files without loading them entirely. So we have a header file, which lists the contents of the other files. It&#8217;s like an inventory list. When the compiler is working on marine.c, it loads the header file weapons<b>.h<\/b>. Then the compiler can say, &#8220;Oh, I don&#8217;t know what the code for WeaponReload () looks like, but according to the header file I can tell that the code exists. I&#8217;ll just keep compiling and trust that the code for WeaponReload () will show up later when I&#8217;m compiling some other file.&#8221; This way the compiler can know that WeaponReload () exists, and the typo WeaponRelaod () doesn&#8217;t, enabling it to catch your error.<\/p>\n<p><!--more--><\/p>\n<h3>Vexation #4: Maintaining Header Files is not Programming<\/h3>\n<p><div class='imagefull'><img src='https:\/\/www.shamusyoung.com\/twentysidedtale\/images\/vex_paperwork.jpg' width=100% alt='Problem: We have an information sorting problem. Solution: Write a program to do the sorting for us. New problem: The source code for the solution is itself an information sorting problem.' title='Problem: We have an information sorting problem. Solution: Write a program to do the sorting for us. New problem: The source code for the solution is itself an information sorting problem.'\/><\/div><div class='mouseover-alt'>Problem: We have an information sorting problem. Solution: Write a program to do the sorting for us. New problem: The source code for the solution is itself an information sorting problem.<\/div><\/p>\n<p>People defend header files by pointing out how useful it is to have them. You can get an overview of the weapons code by glancing through weapons.h, rather than doing a full read of weapons.c. Of course, it&#8217;s always super-useful when other people do a bunch of work for you. The question isn&#8217;t whether or not they&#8217;re useful, but if it makes sense for programmers to create and maintain these things.<\/p>\n<p>Header files are generated manually by the programmer. You write the code for WeaponReload (), and then you add the definition for WeaponReload () to the header file.<\/p>\n<p>It&#8217;s the programmers job to keep Weapons.c and Weapons.h in sync. Changes to one might necessitate changes to another. The list is nice to have, but it&#8217;s not <b>always<\/b> useful, even though you <b>always<\/b> need to create it. Suddenly the programmer isn&#8217;t coding, they&#8217;re taking inventory and doing bookkeeping. <b><i>For the computer<\/i><\/b>.<\/p>\n<p>Sometimes header files need to include other header files. Sometimes these dependencies can be circular. A needs B needs C needs A. So you need to arrange things so that files are included in the right order, and you need to add special qualifying lines to help the compiler along. You need to stop it from including the same file more than once so it doesn&#8217;t get trapped in a circular chain.<\/p>\n<p>This is a <b>horrendous<\/b> system.<\/p>\n<ul>\n<li><b>It greatly inflates compile times.<\/b> Cars don&#8217;t care about guns, but they do care about marines, and if you want to refer to marines then you need access to the data types that marines use. So compiling cars.c means parsing the guns.h header file. That header file might include another, and another, and pretty soon this simple game object is 50 lines of useful code that includes 5,000 lines of header files for the compiler to chew on. And since the compiler is invoked once for every file in the project, it will need to redundantly parse those 5,000 lines many, many times.<\/li>\n<li><b>It makes it annoying to add things to the project.<\/b> If I add a backpack data structure and make it part of the space marine, then I have to go to every single file in the project that refers to the marine and add the line #include &#8220;backpack.h&#8221; to it.\u00a0 (Or include backpack.h within spacemarine.h, exacerbating to the problem above.)<\/li>\n<li><b>Files need to be compiled more often.<\/b> Bullets don&#8217;t interact with backpacks, but because of the way header files connect to each other, making changes to the backpack header will force bullets.c to need a recompile.<\/li>\n<li><b>Changing the data structures might necessitate re-arranging all the header files.<\/b> If I make a change that means bullets.h is needed before lootbox.h, then I&#8217;ll need to manually edit all the source files that refer to both.<\/li>\n<\/ul>\n<p>C++ inherited all of this from C. It was introduced in 1985, which is unfortunate. If it had arrived just a few years later, it could have been constructed differently and taken advantage of the hardware gains to compile things on a project level rather than doing everything a single file at a time<span class='snote' title='1'>Although to be honest, this would have been unlikely. Abandoning header files would have been a really big shift. For good or for ill, the prevailing assumption was that C++ ought to be able to parse all the extant C code.<\/span> . As it stands, C++ wastes programmer time (which is and always has been precious) to save on memory (which is ridiculously plentiful at this point) during compile.<\/p>\n<p>Coders will point out that there are ways to mitigate all of these annoyances: We have precompiled headers, header files that include other header files, incremental builds, and a bunch of other things to make this less of a chore. Making it less painful is nice, but this is a hassle that shouldn&#8217;t exist at all. Text files are trivial, programmer time is precious, and this busywork doesn&#8217;t make the program better. <i>The programmer is literally doing all this work to make it easier for the compiler to sort through data.<\/i> That&#8217;s like having a construction worker use a shovel to loosen up the soil before they use the bulldozer to dig the hole. <b>Why is the human doing work to make things easier for the machine?!<\/b> Even if it only takes the programmer fifteen seconds to sort out a header problem, that&#8217;s literally billions of times longer than it would have taken the computer to sort it out.<\/p>\n<p>So much work has been put into making compilers help the programmer by optimizing the code. It will change loops, ignore unused code, and do a bunch of esoteric sorcery to shave off a few processor cycles here and there. But then we still have all these programmers playing this absurd header file sorting game like its 1972.<\/p>\n<p>Header files aren&#8217;t a part of any modern language. Rust, Go, C#, Java, PHP, Swift, Python, Visual Basic, Ruby, and Perl all seem to get along just fine without burdening the programmer a bunch of inventory homework. Still, if you&#8217;re making a AAA game, then you want the power of C \/ C++. And if you want that power, then you need to endure the vexations of header files.<\/p>\n<p>Before we cover the next vexation, let&#8217;s stop for an aside and talk about&#8230;<\/p>\n<h3>Semicolons<\/h3>\n<p><div class='imagefull'><img src='https:\/\/www.shamusyoung.com\/twentysidedtale\/images\/vex_semicolon.jpg' width=100% alt='Why did we choose the semicolon to end a line? Going by how the symbol is used as punctuation for prose, it ought to signal that this is NOT the end of a line. Wouldn&apos;t it be better to have a period mark the end of a line? (The period has other uses now, but when the language was formed they were presumably free to choose whatever symbols they wanted.)' title='Why did we choose the semicolon to end a line? Going by how the symbol is used as punctuation for prose, it ought to signal that this is NOT the end of a line. Wouldn&apos;t it be better to have a period mark the end of a line? (The period has other uses now, but when the language was formed they were presumably free to choose whatever symbols they wanted.)'\/><\/div><div class='mouseover-alt'>Why did we choose the semicolon to end a line? Going by how the symbol is used as punctuation for prose, it ought to signal that this is NOT the end of a line. Wouldn&apos;t it be better to have a period mark the end of a line? (The period has other uses now, but when the language was formed they were presumably free to choose whatever symbols they wanted.)<\/div><\/p>\n<p>In C++, every line must end with a semicolon. This leads to the old programmer adage &#8220;A semicolon is mandatory everywhere it isn&#8217;t forbidden&#8221;. Semicolons have fallen out of favor in the last generation or so and I see a lot of people questioning why a language would have such a dumb feature.<\/p>\n<p>All C family languages use them. So do Java, D, PHP, Perl, and Rust. But Python, Go, Groovy, Visual Basic, and Ruby don&#8217;t. Swift is an odd one, where semicolons are <a href=\"https:\/\/www.programiz.com\/swift-programming\/hello-world\">supported but optional<\/a>. I get the sense that current-day attitudes among the younger coders lean away from semicolons.<\/p>\n<p>I can understand why some people find them pointless. A semicolon is supposed to mark the end of a line.<\/p>\n<pre lang=\"c\">a = a + 1;\r\n\r\nb = a + 2;\r\n\r\nc = a + b;<\/pre>\n<p>The compiler doesn&#8217;t care about whitespace, so you could format that code like this and it would be the same to the compiler:<\/p>\n<pre lang=\"c\">a = a + 1; b = a + 2; c = a + b;<\/pre>\n<p>But don&#8217;t we already have a way to mark the end of a line? That&#8217;s what the return key is for! Why not mark the end of a line of code by actually ending the line of code?!<\/p>\n<p>I can understand why people say this, but let me try to make a case for semicolons.<\/p>\n<h3>The Case for Semicolons<\/h3>\n<p><div class='imagefull'><img src='https:\/\/www.shamusyoung.com\/twentysidedtale\/images\/vex_ide.jpg' width=100% alt='In the old days we&apos;d only view one file at a time in a DOS-style window. These days your IDE can stck files side-by-side so you can get more information on the screen.' title='In the old days we&apos;d only view one file at a time in a DOS-style window. These days your IDE can stck files side-by-side so you can get more information on the screen.'\/><\/div><div class='mouseover-alt'>In the old days we&apos;d only view one file at a time in a DOS-style window. These days your IDE can stck files side-by-side so you can get more information on the screen.<\/div><\/p>\n<p>Because of the kind of work I do &#8211; procedural object generation &#8211; I sometimes wind up with a lot of <b>really<\/b> long lines. I&#8217;ll have a lot of short lines that only use the first 10 or 20 columns of horizontal space, and then a block of enormously long lines that extend far beyond 100.<\/p>\n<p>Some of the code can get pretty complicated and hard to explain, but here&#8217;s a simplified example:<\/p>\n<pre lang=\"c\">\/\/Put the hat on the player's head.\r\n\r\nhat.MoveTo (Vector3D (player.avatar.position.x, player.avatar.y + player.height, player.avatar.position.z));<\/pre>\n<p>We&#8217;re trying to put a hat on a character&#8217;s head in 3D space. So we take the player&#8217;s origin<span class='snote' title='2'>Typically, this is the point at the base of the model, even with the soles of the feet.<\/span>, add the player&#8217;s height to the Y component, and move the hat to the resulting location.<\/p>\n<p>In my experience, most coding projects encourage you to keep individual lines of code under 80-ish characters long. Back in the old days, this was the limit of how much text you could fit on the screen horizontally. We&#8217;re obviously way beyond that now. I just tested it in my IDE,\u00a0 and even with a large font my 1080p monitor can easily fit ~150 characters on a line without needing to do any horizontal scrolling. However, this is still discouraged. As monitor resolutions have gone up, the preference seems to be for having <b>more<\/b> files open side-by-side. Rather than leaving this vast expanse of unused empty space on the right, why not split the window in half and show different files on the left and right sides?<\/p>\n<p>The line of code above isn&#8217;t outrageously long. It&#8217;s only 108 characters, plus some indenting depending on how deeply this is nested. If a single line jutted out to column 108, most project managers would overlook it. But at some point, that line sticks out so far that you can&#8217;t see it without horizontal scrolling. Having bits of code hidden beyond the right edge of the screen is annoying and scrolling back and forth to read code sucks.<\/p>\n<p>In a language with semicolons, I can take that single line of code and break it up like so:<\/p>\n<pre lang=\"c\">hat.MoveTo (Vector3D (player.avatar.position.x,\r\n\r\nplayer.avatar.y + player.height,\r\n\r\nplayer.avatar.position.z));<\/pre>\n<p>To the compiler, that&#8217;s still a single line of code, because a line doesn&#8217;t end until it sees the semicolon. In a language without semicolons, you can&#8217;t do this. If a line is ridiculously long, you need to either break it up into a series of discrete operations or tolerate the horizontal scrolling.<\/p>\n<p>You could shorten this line like so:<\/p>\n<pre lang=\"c\">Vector3D hat_pos = player.avatar.position;\r\n\r\nhat_pos.y += player.height;\r\n\r\nhat.MoveTo (hat_pos);<\/pre>\n<p>What I dislike is that I&#8217;m creating this extra variable. That variable will hang around as long as it&#8217;s in scope and there might be some overhead to creating it<span class='snote' title='3'>Variable constructors can often hide a bunch of operations from you, so there might be an unseen cost to creating a new variable. Although the one-line version might ALSO create a temporary variable. It&#8217;s complicated.<\/span>. This variable isn&#8217;t needed by the code and <i>it only exists for the purposes of layout<\/i>. Making additional variables to solve formatting and spacing problems is like wearing oversized shoes because you like the extra spacing around the Nike logo.<\/p>\n<p>Like I said above, the whole point of having the compiler ignore whitespace is so that we can format code in whatever way makes visual sense to the reader. Semicolons make it easier to do that by decoupling how we view the code from how the compiler interprets the code.<\/p>\n<p>In Jai, Jon Blow has specifically said that he&#8217;s &#8220;agnostic&#8221; on semicolons. Last time I looked, Jai seems to use them, but I get the sense that he&#8217;s not attached to them and could easily abandon them if he found a good reason. Like Blow, I don&#8217;t think this issue is <b>that<\/b> important. It&#8217;s an interesting thing to think about &#8211; particularly if you&#8217;re considering making a new language &#8211; but it doesn&#8217;t need to be part of the programming holy wars. I prefer them, but I&#8217;m perfectly happy using a language that doesn&#8217;t have them. I&#8217;m happy as long as the language has one of these two ideas:<\/p>\n<ol>\n<li>The line doesn&#8217;t end until you enter a semicolon.<\/li>\n<li>The line ends if you hit the return key, EXCEPT you can use some special symbol to indicate that this line is continued below.<\/li>\n<\/ol>\n<p>As long as I have the option to have one logical line span multiple lines of text, then I don&#8217;t really care which system we use. I&#8217;m partial to semicolons because I&#8217;ve been using them for 29 years, but there&#8217;s nothing wrong with the alternative.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>I&#8217;ve talked about C++ header files before. Like I said earlier in this series, the C language was designed in an age where memory was scarce and it wasn&#8217;t feasible for the compiler to hold your entire codebase in memory at once. So projects end up broken up into many different files. The file marine.c [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[66],"tags":[],"class_list":["post-48518","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\/48518","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=48518"}],"version-history":[{"count":16,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts\/48518\/revisions"}],"predecessor-version":[{"id":48534,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts\/48518\/revisions\/48534"}],"wp:attachment":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=48518"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=48518"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=48518"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}