{"id":9892,"date":"2010-12-01T12:01:14","date_gmt":"2010-12-01T17:01:14","guid":{"rendered":"http:\/\/www.shamusyoung.com\/twentysidedtale\/?p=9892"},"modified":"2010-12-01T13:41:34","modified_gmt":"2010-12-01T18:41:34","slug":"project-hex-part-6-a-comment-on-comments","status":"publish","type":"post","link":"https:\/\/www.shamusyoung.com\/twentysidedtale\/?p=9892","title":{"rendered":"Project Hex Part 6 – A Comment on Comments"},"content":{"rendered":"

If you remember from last time<\/a>, I’ve got a bug in my program. It’s supposed to look at the terrain and determine which way is downhill, and it’s coming up with the wrong answer. Sometimes. <\/p>\n

I’m going to post a block of code directly from the project. This is the top of the file called Hex.cpp:<\/p>\n

<\/p>\n

\r\n\/*-----------------------------------------------------------------------------\r\n\r\n  Hex.cpp\r\n\r\n-------------------------------------------------------------------------------\r\n\r\n  This module deals with the prickly business of turning a stright grid into \r\n  a hex grid.  It creates the relationships between the points, fightures out\r\n  how they link together, and so on.\r\n\r\n\r\n  \"Hexes\" are built on a normal grid. They are made by connecting points to \r\n  form rows of interlocking \"house\" shapes, like so:\r\n\r\n       \r\n    +--|--+--|--+--|--+--|--+\r\n       |     |     |     |\r\n       |  .  |  .  |  .  |\r\n      \/ \\   \/ \\   \/ \\   \/ \\\r\n     \/   \\ \/   \\ \/   \\ \/   \\\r\n    |  .  |  .  |  .  |  .  |\r\n    |     |     |     |     |\r\n    +--+--+--+--+--+--+--+--+   \r\n       |     |     |     |\r\n       |  .  |  .  |  .  |\r\n      \/ \\   \/ \\   \/ \\   \/ \\\r\n     \/   \\ \/   \\ \/   \\ \/   \\\r\n    |  .  |  .  |  .  |  .  |\r\n    |     |     |     |     |\r\n    +--+--+--+--+--+--+--+--+   \r\n       ^ \r\n       |       \r\n       +---This column gets shifted down.\r\n   \r\n    These are made to look like hexes by taking every other column of points\r\n    and shifting them downward by a half unit. Every vertex connects to three \r\n    others, EXCEPT for the one floating in the center of the hex. \r\n\r\n    There are six different types of points:\r\n    1) Ones that form the tip of a house's roof.\r\n    2) Ones that forn the tip of an inverted house.\r\n    3) Ones at the bottom of a house.\r\n    4) Ones at the bottom of an inverted house.\r\n    5) Ones at the center of a house.\r\n    6) Ones at the center of an inverted house.\r\n\r\n-----------------------------------------------------------------------------*\/\r\n<\/pre>\n
Coders will notice that this is almost fifty lines of nothing but comments.  There’s no actual code here. Just notes.<\/p>\n
Years ago, I made a habit of leaving comments when working on group projects, but never on personal projects. After all, why write notes in code if I’m the only one who will ever see it? <\/p>\n
Of course, I gradually learned how useful comments are, even if you wrote them yourself and you’re the only person who reads them.  You can write a block of code, work on it for days, and recall it in perfect detail. But two years later it can look just as strange and foreign as random code blocks written by madmen on the internet. <\/p>\n
A lot of the discipline of programming is dedicated not to writing code that simply works<\/em>, but code that is easy to understand and reuse. The challenge here is managing complexity<\/strong>. The problem is that programs are too large and complex to fit easily within our limited and highly distracted human brains. We need some way to avoid becoming overwhelmed. We can’t make our programs simpler, so the best we can do is to try and make our source code simpler. <\/p>\n
Some programmers insist on pure object-oriented design. Or a certain style of naming variables. Or a way of formatting code. Consider…<\/p>\n
\r\nif (bFdom) \r\n{\r\n  float fIntr = fBal * fRate;\r\n  fBal = fBal + fIntr;\r\n}\r\n<\/pre>\n
And compare to:<\/p>\n
\r\nif (fdom) {\r\n  bal += bal * intr;\r\n}\r\n<\/pre>\n
Same code. Same behavior. But different programmers will insist that one is right and good, which the other is the work of an idiot. Do you indent lines with space or tabs? Does an opening bracket go on a line by itself?  How are variables named?  How much crap should you cram into a single line of code before you start thinking about breaking it into multiple lines? There are many schools of thought on this sort of stuff and some people take it very seriously. This orthodoxy has grown in complexity over the years as human beings have tried to come up with better ways to avoid drowning in the sea of data that comprises even a mid-size software project.  <\/p>\n
Just thirty years ago things were much simpler. Most non-academic programs were just report generators.  “List out all customers who have not paid their bill in over 90 days and the outstanding balance is more than $100. List the name, address, contact info, and amount due. If they owe more than $1,000 then also print ‘HIGH PRIORITY’ next to their name.”  Simple stuff.  I actually did a bit of this kind of work back in 1993 or so.  Very dull, but very simple.  There were a lot of horrible languages back then, but that was okay. Languages didn’t need to be very good because we didn’t need much from them.  In fact, software was so simple that it was possible (and occasionally required) to make flowcharts to show the flow of a particular program.  I maintain that these were a grotesque waste of time and paper (outside of educational purposes) but there really were companies that kept huge binders of source code and flowcharts for everything they wrote.  <\/p>\n
Software is now incredibly complex and any halfway-useful consumer program is going to be too immense to even contemplate turning it into a flowchart. Even my project – barely in its infancy – tops 5,000 lines of code.  If I lost my mind and wanted to make a flowchart of the thing, I’d need a sheet of paper the size of my living room.  A completed modern game would most likely cover a football field. <\/p>\n
The bad languages of the past had many flaws.  Some were too obtuse.  Some were too verbose. Some were just unable to scale up in complexity without the source becoming unmanageable. The weak were culled. The survivors influenced and shaped the next generation of languages. <\/p>\n
Over the last decade I’ve noticed a lot of people joining the “The Code is the Documentation” line of thinking. Also known as “self documenting code”.  The idea is that the code should explain itself, and comments are a crutch. If you just format your code with enough precision and are anal enough about your variable names, then this will solve all of the problems with managing complexity.  Let’s apply this to that code snippet I used above:<\/p>\n
\r\nif (FirstDayOfMonth) \r\n{\r\n  Interest = Balance * InterestRate;\r\n  Balance = Balance + Interest;\r\n}\r\n<\/pre>\n
To me, that makes a bigger difference than anything the coder might do with spaces or tabs or where they stick their damn curly braces. Even a non-coder has a pretty good chance at being able to look at this and tell what it does. <\/p>\n
But I disagree with the notion that comments are a crutch.  The most important aspect of my code – and the most complex – is the way I’m cutting a grid of squares into a grid of hexes. That is complicated business.  I don’t care what you name your variables, the only way to explain that stuff to another programmer (or yourself, in the future) is to write it down. Even if that means drawing diagrams using ASCII art. When I began this project I found myself reviewing my old terrain project<\/a>.  The ASCII diagrams I’d put in that code were invaluable for helping me to understand what was going on.  Five minutes of work in 2006 just saved me an hour of confusion here in 2010.  (Not to mention how nice it was to have it there during the project, and for everyone else who downloaded the source.)<\/p>\n
So many of our struggles with language syntax, formatting, and usage are just so that we can more readily understand code that has already been written.  If you’re unhappy with your current programming language then maybe changing languages will solve your problems.  But maybe you just need to leave yourself better notes.  <\/p>\n
As for fixing my bug.  It was twofold.  The first problem was that the code I’m using to import bitmaps is screwy.  If you remember, I’m using a grayscale image for my topography, where brighter = higher. For some reason, the brightness values are getting reduced.  There should be 256 distinct levels of brightness, but the values ‘m getting are topping out at just 23.  With so few levels, a lot of subtle surface detail is lost and areas where there were supposed to be mild slopes were perfectly flat. I’m not going to bother tracking this down.  The problem is with some Windows functionality, and we already knew<\/a> those were rubbish.  This system will be replaced once I start generating the terrain procedurally, so I’ll just ignore it for now. <\/p>\n
The second problem was that this:<\/p>\n
\r\n  static grid_coord   utip[] = { 0,-1,  -1, 1,  1, 1};\r\n  static grid_coord   itip[] = { 0, 1,  -1,-1,  1,-1};\r\n  static grid_coord   ubot[] = { 1, 0,  -1, 0,  0, 1};\r\n  static grid_coord   ibot[] = {-1, 0,  -1, 0,  0,-1};\r\n  static grid_coord   ucen[] = {-1,-1,   0,-1,  1,-1, 1, 0, 0, 1, -1, 0};\r\n  static grid_coord   icen[] = {-1, 1,   0, 1,  1, 1, 1, 0, 0,-1, -1, 0};\r\n<\/pre>\n
Should have been this:<\/p>\n
\r\n  static grid_coord   utip[] = { 0,-1,  -1, 1,  1, 1};\r\n  static grid_coord   itip[] = { 0, 1,  -1,-1,  1,-1};\r\n  static grid_coord   ubot[] = { 1, 0,  -1, 0,  0, 1};\r\n  static grid_coord   ibot[] = {-1, 0,   1, 0,  0,-1};\r\n  static grid_coord   ucen[] = {-1,-1,   0,-1,  1,-1, 1, 0, 0, 1, -1, 0};\r\n  static grid_coord   icen[] = {-1, 1,   0, 1,  1, 1, 1, 0, 0,-1, -1, 0};\r\n<\/pre>\n
If you don’t see the difference, don’t worry about it.  It was a single misplaced minus sign. Took me a few hours to find it, though.<\/p>\n
I guess we should at least look at a screenshot after slogging through all of that.<\/p>\n
hex_edges15.jpg<\/td><\/tr><\/table><\/p>\n","protected":false},"excerpt":{"rendered":"
If you remember from last time, I’ve got a bug in my program. It’s supposed to look at the terrain and determine which way is downhill, and it’s coming up with the wrong answer. Sometimes. I’m going to post a block of code directly from the project. This is the top of the file called […]<\/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-9892","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\/9892","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=9892"}],"version-history":[{"count":0,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts\/9892\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=9892"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=9892"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=9892"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}