programming |

The Beginning... When I first started my Computer Science degree program, I remember the various discussions on how and when to comment code. Each text book that I read had different views on when and why someone should comment their code. On top of the different textbook teachings, each of my professors seemed to have different standards on comment requirements: ranging from some not mentioning comments to some deducting points if comments were not present. One common trend was that the quality of code comments did not matter. My internal thoughts were that commenting in school was simply a lot of noise. We were shown practices where we would comment everything and not necessarily in a good way. I would see things such as: [code language="java"] // declare counter int counter; // initialize counter int counter = 0; // loop printing numbers while (counter < 10){ System.out.println("Number: " + counter + "."); counter++; }//end while loop [/code] While this code is communicative, it's also busy and the extra markup is distracting (in my humble opinion). More so, any programmer would know exactly what this code is doing without the comments. Of course, this is pretty basic stuff, what struck me was that the comments that we were required to write in school, went against my natural inclination to communicate decisively and not just because I could. Wait what? Let me clarify a little. I believe that communication is important in many situations, but sometimes communication can be more confusing when it's not clear, concise and free of extra irrelevant information. It's like someone trying to tell you that they are ready for dinner by singing the National Anthem while inserting the words "I'm ready for dinner" somewhere within the song -- it's just extra unneeded noise. I personally feel as though unneeded comments can play the same role within our code. So, what now? I vividly remember my Google searches on a standard for commenting code and what I found was troubling for a new developer at the time. Within one forum or within a single resource there were many different opinions broadcasting why their means of commenting was the best. There were folks lobbying that code should be self documenting and that comments were unnecessary in many cases. There were others that felt that more communication didn't hurt and whatever meta data could be added to the code base would only benefit the project, not harm it -- specifically for new members to development teams. The two sides warred with many people also falling in between at different areas of the spectrum. The one thing that was clear was that there was in no way a specification when it came to commenting code. With experience, came clarity... It wasn't until I started working on a development team, that I started to find my own practices for code comments. First and foremost, I tend to lean towards code that is self documenting. I use explicit comments when there is business logic specific to that code that may not be abundantly clear to the person that is maintaining the code. I am also primarily a Java developer so I believe in commenting in order to get all of the benefits from the Javadoc functionality. I've found that usually if there is a need to comment sections for flow, there is a better design that can be accomplished without using comments such as breaking the code out into different classes or using private or helper methods and descriptive variable and method names to add concrete metadata to the code. This methodology is not new and can be found in well-known software books such as Clean Code by Robert C. Martin. I've found that taking more time to think about the design of the code, leads to fewer comments being needed. Many may think that comments aren't hindering the program in any way since the compiler ignores comments. This is true, but comments can be easily ignored by the programmer, as well. I've seen situations where code was changed to fit a new business need, but the comments for that code was not updated. This leaves very deceptive code that can be more confusing than helpful. In some situations, the original comment was necessary and the developer updating the code should have been more careful. But I've also seen in some cases where the newly-deceptive comment was simply meta data that could have been placed in an external documentation source such as a wiki. In this situation the wiki was updated, but the source code documentation was not. All-in-all, I believe that it's important to find the standard on the project that we are working on. Having a specification is a helpful means of determining how code should be commented, for a project may have a specific standard that should be followed. However, in many cases, it's up to the developer to find a happy medium in the spectrum of commenting paradigms that exist today. I suppose that one test we can use for ourselves is to return to code that we wrote say, 6 months ago and see if we could follow it. Is there enough information to understand the flow and purpose of the code? Would refactoring the code make it far more clear to a new comer? There's always room for improvement, moreover, returning to our old code is a great way test our own system of commenting. I'll leave you with this: what I can say is that my current standard for commenting is completely different than what I was taught in school. However, it feels really good to have a personal standard, developed through my own research and experience.

My Thoughts on Commenting Code

Take a Look

In the past, I have spent hours watching tutorials on how to use Unity, and I've also attended a Game Jam where the engine we used was Unity. So, although I do not consider myself a complete noob, I feel as though I do lack some fundamental knowledge that I would like to dig deeper into. With that said, I decided to start the Complete Unity 5 Developer course on Udemy. I purchased this course when it was on sale, at the beginning of the summer and only used it as a reference when I needed some assistance in a particular area. But after a recent decision I made to streamline my focus (I may write a post on that later), I decided to really sit down and take this course from start to finish. I'm extremely happy about my decision thus far Usually, whenever I sit through a programming tool's training, I want to pull my hair out because of the elementary concepts that are covered in the content. I always feel the urge to skip around and sometimes I feel as though I'm missing out on small nuggets of information that I could really benefit from. This leaves me with a dilemma, do I sit through the boring stuff for the possibility of some new piece of information? OR do I skip around and forgo the hair pulling in exchange for the ability to learn at a rapid pace? However, I find that the way that this particular course is structured, I don't feel as though I'm missing out on anything if I just play it in the background while I go on my own. If I hear something that piques my interest, I tab over and check it out, otherwise I go on my merry way. Also, there are some good nuggets there about Game Design Documents and how to properly ask questions, which I found really beneficial. How will I share what I've learned? By no means are the things I'm learning things that I would want to put in my portfolio. But I want to share them, so I will do that through my blog :). After just a couple of hours (mostly spent feeling out the tools), I was able to build my first full game from an empty project to a build uploaded to my website. The game concept is straight from the tutorial and the dialog is rather dry (I can't deny it). But I'm proud of my little game and I can not wait for what's to come in the near future. Want to check it out? Make sure you're in a browser other than Chrome :) and click below! Prison Game Where to now? I'm not a game writer lol. So, I'm partnering up with a good author friend who has agreed to help me create a new Text Adventure game. He'll do all of the writing (thank God) and I will do the programming. I totally can not wait. Stay tuned, as always :) Want to get your feet wet with game development? You really should try Unity, it's free for personal use.

Join me as I learn Unity 5

Take a Look

We've all been there before. We pull a fresh copy of our project and now it's not working. If you're on a team project, trying to pinpoint where the issue started can seem like a nightmare. Well, for the first time since I started working on our game project (my internship), I was unable to run the game, and there were roughly a month's worth of commits between the fresh pull and the last time that the game worked properly on my computer. My first instinct was to perform an expertly executed table flip and walk out of the room. But instead, great tips from my friend helped me through a pretty awesome bit of functionality of git, git-bisect. So what is this git-bisect thing you speak of? Well, it's a way to step through your commits while git determines which commit was the culprit. Groovy, huh? Git bisect will automatically figure out which commits need to be tested in order to pinpoint which commit is causing your program to fail. So, how does this work? First, you have to let git know that you are about to begin bisecting the code. [code language="python"] $ git bisect start [/code] This toggles the "bisect mode" and starts the bisecting process. Next, you have to let git know which commit is bad: [code language="python"] $ git bisect bad [/code] Usually this is on the current commit. After this, you have to find and checkout a commit roughly near the last working commit. This does not have to be the exact last working commit, git will help determine this info, you just need to find a previously working commit to flag. In my situation, it had been awhile, so I just moved the HEAD back 50 commits. [code language="python"] $ git checkout HEAD~50 [/code] Then I tested the game and determined that it worked. So now I have a rough point, again in my case, it had been quite some time, you may either know the commit or only have to go back a few commits to test. Either way, now it's time to flag the working commit so that git has a range to bisect. For the first working commit, you have to tell git the actual commit, git rev-parse HEAD will give you the current commit, and then you can pass it through to git using the "git bisect good" command. [code language="python"] $ git rev-parse HEAD $ git bisect good [commit] Bisecting: 14 revisions left to test after this (roughly 4 steps) [/code] Note that if your shell supports it, you can combine the above commands to one: git bisect good $(git rev-parse HEAD) Now git tells us that it has determined which commits needs to be tested, after each bisect, you have to recompile and test your code to see if the problem still exists. In my case, the code was still not working so I flagged that commit as being bad. [code language="python"] $ git bisect bad [/code] Git will continue going through the steps, each time you run your code to see if the problem exists, each time entering the command "git bisect good" if it is working, or "git bisect bad" if it's not. Finally, you will run out of steps and git will spit out information about the culprit commit that is causing you so much heartache. After you've noted the offending commit, you have to let git know that you are done bisecting and it will reset you back to the commit prior to beginning the bisecting process: [code language="python"] $ git bisect reset [/code] I found this process pretty awesome. In my situation, when the game did not run, I expected that there was an issue in the very last commit and that everyone else shared the same issue. But after verifying that we were all on the freshest copy of the game and no one else was able to duplicate my issue, I was left trying to determine a system-specific bug, and only I could handle that. This git functionality was very useful in helping me determine the origin of my issue.

Git – The Lost Files : Git Bisect

Take a Look

Photo Source I've made it to Day 3 of learning the programming language, Swift. So far, I have to say that I have been enjoying the syntax. I still type random ";" out of habit, even though I have experience with scripting languages like Lua and Python, I still tend to click the good old ";" out of habit. There are some features that I found interesting such as the way strings and variables are concatenated using the \() formatting. At first I found it obnoxious, but when I had to do stuff with the variables, I found this syntax much easier to read and less confusing when manipulating the variables. Another feature that I'm enjoying is the function syntax. In this particular example, you're able to pass through a series of numbers just by simply using Int... I found this a pretty cool and useful feature. [code language="python"] func sum(numbers: Int...) -> Int { var sum = 0 for number in numbers { sum += number } return sum } sum() sum(100, 200, 300) [/code] I am also enjoying that some of the things that I loved about Python are similar in Swift, like the "for" loop syntax. However, in Swift it's even better, in my opinion, because the loops have brackets as opposed to colons. The familiarity of brackets always makes me feel welcome in any new language that I'm learning. Overall, I'm having more fun than I should discovering and learning Swift so far. Soon, I'll get to the point where I'll begin to experiment with Swift in creating an iOS app. Stay tuned!

Learning Swift – Day 3

Take a Look

playgroundSwift — Xcode’s Playground

Take a Look

Archive

Tag: programming

My Thoughts on Commenting Code

Join me as I learn Unity 5

Git – The Lost Files : Git Bisect

Learning Swift – Day 3

Xcode’s Playground