Gamasutra: The Art & Business of Making Gamesspacer
View All     RSS
October 1, 2014
arrowPress Releases
October 1, 2014
PR Newswire
View All





If you enjoy reading this site, you might also want to check out these UBM Tech sites:


 
Unconventional Tips for Improving your Programming Skills
by Livio De La Cruz on 07/02/14 03:35:00 pm   Featured Blogs

The following blog post, unless otherwise noted, was written by a member of Gamasutra’s community.
The thoughts and opinions expressed are those of the writer and not Gamasutra or its parent company.

 

The following article was originally posted on my blog Superheroes in Racecars.

pikachu-with-sandbag

There are plenty of good resources out there that teach the technical skills that are necessary for becoming a good programmer, but I’ve seen only a few that give you the more personal lessons that you often only learn through experience or trial and error. In this article, I’m going to share with you some of my own habits and skills that I’ve gained over the years to help me do better work.

This article is based on a post I made over a year ago on the UofA CS Facebook Group in response to someone’s question about how you can become a faster programmer. Instead of posting about tools and keyboard shortcuts, most of my tips are about how to get yourself to think faster, along with a few tips for avoiding time-consuming mistakes.

1. Eat Well, Sleep a Lot, and Stay Hydrated!

drink-water

Why do so many (novice) programmers brag about how much sleep they lost while working on their programs? Why do people assume that programmers only eat junk food and sugar-saturated energy drinks? Who seriously thinks that neglecting your own health is an appropriate way to do what you love?

Anyone who is serious about doing good work in software engineering (or in any profession) should also be serious about taking care of themselves. As Sir Ken Robinson suggests, people often spend too much time “living in their heads”, and so they tend to undervalue and underutilize their own bodies throughout their lives. In our case, programmers often tend to underestimate just how big of an impact their bodies have on their performance as an engineer. Programming is a task that requires a lot of focus and energy, and so it’s obvious how much your performance can suffer if you’re frequently sleep-deprived or malnourished.

Having a consistent sleep schedule with eight hours of sleep each night is crucial for maintaining your alertness and ability to think quickly. It can also give you an incredible amount of stamina for when you do find yourself needing to sacrifice sleep for one reason or another. Also, since losing sleep often hurts your ability to focus, staying up late to finish something is often a lot slower and more painful than simply waking up early to do it.

In addition to sleeping well, eating a healthy diet also helps keep you in a good mood and gives you the energy you need to tackle big problems. If you truly want to work hard, then you’re going to need full meals to fuel you, not empty snacks. Breakfast is often cited as the most important meal because eating fires up your metabolism, thus giving you plenty of energy to tackle the day with. I tend to treat my meals as sacred, meaning that I never skip them unless I have a good reason for it. When you’re working, it’s surprisingly easy to forget that you’re hungry, so it’s important to tie your meals to your routine so that you don’t accidentally starve yourself.

I personally drink a ton of water while working, and while I’m not sure what kind of an effect water has on my performance, most programmers I know make sure to at least keep a water bottle with them at all times when working. I prefer water to any other drink because I can drink as much of it as I want without worrying about any negative health effects (of course, I never even get close to getting over-hydrated), and I also find that water’s the only thing that actually quenches my thirst.

The benefit of eating and sleeping well is that it decreases your reliance on certain beverages or snacks to give you energy, and you can instead learn to rely on your own strength and stamina. If you do find yourself needing a boost of energy, then energy drinks are definitely not the way to go, since the negative health effects mostly outweigh the benefits. Lots of people drink coffee, but there are also other ways to get more energy, such as actually getting some rest.

2. Take Periodic Breaks, and Get Increased Productivity

take-a-break

Whenever I tell people that taking breaks is good for them and that it will actually make them more productive, I never meet as much resistance to this idea as when I’m talking to programmers. People are used to thinking about their productivity in terms of time, and they will often plan their time with the false assumption that they always work at the same level of productivity. In addition to time, you also need to think about energy, which determines how efficiently you work within a given amount of time. If you can learn to properly manage your energy, you’ll be able to get much more work done within a smaller amount of time.

The first step towards being more aware of your personal energy levels is to take breaks. Much in the same way that a runner gets weaker after running nonstop for a considerable amount of time, your energy levels and amount of focus also decrease the longer you work without a break. I typically force myself to take a 15-minute break after every 90-minutes of work. The breaks have as much of an effect on your body as it does on your own psychology. For instance, I usually find myself throwing much more energy into my work because I know that a break is coming soon to let me recharge.

Because focus is such an important part of the programming process, I often rely on timers to tell me when it’s time to take a break and when it’s time to get back to work. It’s just too easy to lose track of time while working, and so this frees me from the stress of constantly checking the clock. However, it does take a certain level of discipline to get yourself to actually take that break, because you’re often “in the zone” and you feel like it’d be unproductive to stop working at that moment. However, I’ve found that postponing or skipping a break is usually not a good idea because you’ll find yourself getting sloppy or unproductive as your energy levels continue to decrease. You’re usually much better off just taking the time to recharge and then tackling the task with a bunch of renewed energy after the break.

Here are a few rules of thumb for taking effective breaks. First, get off the computer and walk around a bit, while focusing your eyes on far away objects. Maybe go outside and get some sun, or find some stairs to climb. Do anything that will help you wake your body up after sitting down all day. Next, you must stop yourself from thinking about work. Your break is your time to recharge, and the best way to do that is to just unwind and let your mind rest. If your mind is still racing around, then that’s like a jogger wasting their break by running in place the whole time. I’ve met a few people who are just not good at unwinding, and they are some of the most perpetually stressed people I know.

Some people are simply afraid to unwind, because they fear that they’ll have trouble getting back into the groove of high-focus work, but that usually doesn’t happen unless you’re just dead tired. The next section has plenty of tips for helping you get back into the groove after a nice break.

3. Learn How to Pump Yourself Up for Work

little-mac-smash-bros.

If the last section was about unwinding, then this one is about getting yourself back in the zone. It helps if you imagine yourself as an athlete who’s about to begin a big match. Taking a strong, deep breathe usually helps me wake myself back up, almost as if I was gathering my strength to pick up something heavy. I also tend to fidget a lot while working, mostly by tapping my feet, and while most of the time it’s a subconscious habit, there are times when I consciously choose to fidget in an attempt to wake myself up and get my blood flowing because it’s time to work hard.

I also tend to listen to a lot of upbeat music while working. Almost my entire music library is really upbeat, but I also maintain a playlist called “upbeat” that I specifically turn to for when I need a boost of focus. I find that it helps to work with music that you’ve already heard a thousand times because then you can safely tune it out as you get more focused. Whenever I listen to new songs or to online radio stations, I usually find myself getting way too distracted by all of the new music.

It’s also important to avoid multi-tasking. Whether you’re watching a TED talk or eating a sandwich, if you’re doing anything else while working, it’s just going to decrease your focus. Many people probably think that that loss of focus is probably worth it, but I find working with low-focus to be pretty irritating for me. Whenever I work while distracted, I just can’t perform at the same level that I’m used to performing at, and it just frustrates me because I can clearly see how sloppy I’m being or how much time it’s taking me to do something that I typically do in a few minutes.

All of these techniques for getting in the zone are really only effective if you also take periodic breaks. Otherwise, you’ll just burn yourself out pretty quickly and start to underperform. It’s also worth noting that being in the zone is not the same as rushing through your work. Rushing will only promote sloppiness and poor judgments, whereas getting in the zone is simply about making sure your head is 100% in the game.

4. Don’t Work More than Eight Hours Per Day

turn-off-the-computer

This particular tip is something that I believe pretty strongly in. When you force yourself to work only a certain number of hours per day, you’ll actually find yourself completing more work per day, not less. When you don’t have a time limit on your work day, you’re more inclined to slack off under the idea that you could always stay late and finish if you don’t have time. But once you realize that you’re only at work during a few precious hours per day, then you’re going find yourself working harder in an attempt to stop those hours from going to waste.

I’ve heard many stories about people who frequently worked overtime lamenting the fact that they now had to work regular hours after starting a family. To their surprise, they usually find themselves to be more productive, more alert, and just plain happier with their lives. If for whatever reason you still find yourself running out of time after working only eight hours a day, then the real problem was poor planning skills with impractical time estimates.

5. Stop And Think About What You’re Doing

different-paths

This might be the closest thing to a “rookie mistake” on this list, but I’m still mentioning it because I saw way too many students making this mistake during mock interviews. One of the easiest ways to waste your own time is to jump straight into a problem without thinking things through. Your first idea on how to solve a problem is most likely not going to be the “best” way of doing it. A good developer knows how to balance the trade-offs of several different solutions in order to pick the best one that fits the current situation. Experienced developers also have a good sense for when “there has to be a better way”, which prevents them from foolishly going down arduous paths.

There’s a lot of creativity that can go into how you think about the problems that you solve. It’s about more than just “what’s easiest?” or “what’s the most elegant way of doing this?” You also have to think about how risky a certain solution will be. For instance, you could use a new framework to solve a problem for you, but who knows what kind of unforeseen problems you’ll have while learning that new framework? Or if you go with an overly clever approach to the problem, then how painful and confusing will it be to maintain the code for this solution?

Another solution that is frequently overlooked is to simply do nothing at all. Sometimes the problem you were thinking about simply isn’t worth the effort to solve. Sometimes you might even able to hide the problem under the rug, either by directing the user’s attention elsewhere, or by making the bug seem more like a feature. Finding creative solutions such as these often requires that you always keep a strong grasp on what the actual problem is. For instance, if your code is slow, the real problem is usually “users don’t have the patience for this”, and it’s important to remember that optimizing the code is only one of many possible approaches to that problem.

6. Get Good at Writing Documentation

2014-07-01_14.19.38

Yeah, yeah, we all know how important it is to document our code, right? Part of the reason why programmers tend to have a love-hate relationship with writing documentation is because we’re typically not fans of being forced to do things that we think are unnecessary. But this sentiment mostly comes from a confused understanding of what documentation is for. I tend to see documentation as mainly being a tool for communication, meaning that when I write comments, my task is to make sure that whoever is reading it (whether it be a team member, a future employee, or myself) is able to understand the code that it describes. When people resist writing documentation, they usually say it’s unnecessary because either: (1) the code is obvious, (2) everyone on the team already understands it, or (3) there’s no way that they’re going to forget what the code does.

Because it’s so easy to make bad assumptions (such as the ones stated above), I personally prefer to take a risk-oriented approach towards writing documentation. For instance, instead of asking myself “Does everyone already understand this?”, I instead ask “What are the chances that someone will ever be confused by this?” If I think there’s even a small chance, then that’s usually good enough reason to write at least something down.

It also helps to show your code to someone and to actually see how they’re confused by it, so that you have a clearer idea of what points of confusion your documentation is supposed to help fix. Much in the same way that bugs are fixed after discovering them, many good comments are written after finding those points of confusion.

7. Get Good at Taking Notes and Writing Down Your Ideas

iron-man-hologram-interface

If the purpose of documentation is communication, then the purpose of writing notes for yourself is to help you stay organized. Sometimes you just want to remind yourself of something, or maybe you’re using your notes as a way of sorting out your own ideas. Unlike documentation, these kinds of notes are personal, and they’re tailor-made to fit your own unique way of understanding things.

Because it’s so personal, it’s important to experiment with different tools and techniques for taking notes so that you can find the method that works best for you. I tend to use different tools for different things. For instance, if I’m maintaining a TODO list, I usually rely on simple text files. If I want to write down a reminder, I use apps like Google Keep to automatically remind me at the appropriate time. And if I want to take notes on something particularly complex, I’ll usually turn to pen and paper so that I’m free to make drawings.

A good programmer should also know the limits of their own memory, which will only get weaker once he or she starts getting old. The worst thing about forgetting an idea is that you don’t even notice when it’s gone, and so there’s a small amount of stress that goes into making sure that idea isn’t forgotten. As Jesse Schell wrote in The Art of Game Design:

“When you think of an important idea, and you don’t write it down, it kind of bangs around up there, taking up space and mental energy, because your mind recognizes it as important and doesn’t want to forget the important idea. Something magic happens when you record it — it is like your mind doesn’t feel the need to think about the idea as much. I find it makes my mind feel clean and open, as opposed to cluttered and cramped.”

I find that notebooks are best for recording ideas, because it’s sometimes easier to explain ideas with drawings. Of course, as with any personal note system, it’s good to experiment with several different tools for recording ideas so that you can find what works best for you.

8. Know When to Take Shortcuts

warpzone

I think most programmers will agree with me when I say that the “right” way to program something isn’t always the wisest choice. Sometimes the solution that does things the most efficiently or uses the least amount of resources just isn’t worth the hassle when compared to the simpler approach that just gets the job done. Sometimes the system that covers all possible use cases and is polished to perfection is just overkill for what you need at the moment.

Knowing when to take a shortcut and when not to is a fairly tricky skill to master. It requires that you have a strong grasp on what your main objective is whenever you’re working. For instance, if you just want to see if the feature is a good idea or not, then you’d want to implement things as fast as possible so that you can answer that question quickly before making the commitment to implement the feature perfectly. This happens a lot in game design, when sometimes you just need to iterate a lot on a design problem, but you don’t want to waste time working too much on a feature that might just get removed in the next iteration.

9. Know When to Clean Up Your Code

mario-sunshine

Working in messy, disorganized code is like trying to live in a messy, disorganized house. You constantly stumble over things, everything smells, and nothing is placed in its logical location. It’s important to remember that these messes are often the natural result of the programming process, especially if you’ve been taking a lot of shortcuts lately. But much like how you’d clean a kitchen after cooking, you must also clean your code after you’ve finished getting your features to work.

Having “clean” code is often a result of several different qualities, such as having good documentation, being well formatted, deleting commented-out sections of code (you’ll never use them anyway), and making sure that everything is organized in a way that makes sense. When working on object-oriented programs, it’s common for class responsibilities to start deteriorating as you add more features, and so a proper refactoring job might require you to redesign the structure and responsibilities of multiple classes. Comments also have a way of decaying over time, so it’s important to make sure that they get updated every once in a while.

Aside from all of the productivity benefits that come with not tripping over messy code, frequent refactoring can often have really useful side-effects. Through the act of re-reading and reorganizing code, not only do you tend to get more acquainted with the code base, but you also restructure parts of it to be easier to understand, which is in turn easier to remember. This is immensely useful for debugging, because if you can remember where everything is and what it all does, then you’ll be much more likely to solve bugs quickly.

It’s also good to know when it’s okay to not refactor something. I personally prefer to refactor code only when its messiness is starting to be a problem, or when it’s obvious that it will be a problem in the near future. So say I just finished writing a class that is pretty confusing, but if there are no plans to touch that class again anytime soon, then it might just be a waste of time to refactor it, especially if it’s a class that is pretty isolated from the rest of the program. Only when the messiness starts to get in the way of progress (and on my nerves) will I start to refactor it.

10. Get Really, Really Good at Debugging

phdcomic-debugging

If there’s a single skill that you can master that will have the biggest impact on your programming abilities, it would probably be debugging. Everyone hates it when they run into that one bug (or series of bugs) that seems to stump them for hours. There’s a lot that can affect how quickly you solve bugs, such as how much experience you have, your ability to stay calm when frustrated, and how well you understand the technologies that you’re working with.

Experience probably makes the biggest difference, however, because it’s just easier to find bugs that you’ve already seen before. I was lucky enough to have gained a ton of debugging experience while being a teaching assistant for several different programs that teach people how to program. When you’re in a computer lab surrounded by students who need help finding bugs, you start to develop a fairly methodical process for hunting down bugs quickly.

At it’s core, debugging is basically about testing your assumptions. Sometimes you assumed that you wrote everything correctly, when you in fact told the computer to do something else. Or maybe you assumed that your algorithm produced the correct result, when it really didn’t. Or perhaps you misunderstood how a piece of technology worked, in which case the bug can be a huge pain to track down (for example: modulus operations are pretty easy to misunderstand). Some of the hardest bugs can come out of the complex interaction of multiple large systems, which means that understanding the bug requires knowledge of how each of those systems work (this is why it’s good to know about operating systems and networking, even if you don’t plan to work in those fields).

It’s funny how debugging is such a big part of the programming process, and yet programmers rarely plan for it when estimating how much time they’ll need to implement something. Even when implementing easy features that we are 100% confident about getting right, we still tend to run into bugs, just because of how easy it is to make mistakes.

11. Learn to Predict Bugs Before They Appear

i-was-afraid-this-would-happen

When I’m implement something, I tend to maintain a mental list of everything that might go wrong with the system and what that bug might look like if it did go wrong. For instance, I often get lazy when it comes to making sure that values passed into functions have acceptable values, but I at least take the time to imagine what would happen if the wrong parameters managed to go through (so if I was making a platformer game, for example, then maybe the player would start running the wrong way). Then when a bug emerges that looks like one of my previous predictions, I’ll instantly have a theory on what’s causing the bug, without needing to pick apart any code.

Almost every programmer has a habit of asking himself/herself the following question every now and then: “What would happen if this was the case?” The difference here is that I simply take it a step further and think about what the effects might be outside of the immediate, nearby lines of code. I imagine what might happen if that bug were to interact with the other systems of the program and how it might appear on screen when the program is running. Of course, this requires that you have a strong understanding of the systems that you’re implementing and the technologies that you’re working with.

Conclusion

So what do you think makes you a better programmer? Do you have any weird habits that help you do better work? Was there anything I suggested that you disagreed with? If so, then please post about it in the comments below!

Thanks for reading.


Related Jobs

Bohemia Interactive Simulations
Bohemia Interactive Simulations — ORLANDO, Florida, United States
[10.01.14]

Game Designer
Whow Games GmbH
Whow Games GmbH — Hamburg, Germany
[10.01.14]

Games Developer
Bright Future GmbH
Bright Future GmbH — Cologne/Koeln, Germany
[10.01.14]

Senior ActionScript Developer Mobile
Bohemia Interactive Simulations
Bohemia Interactive Simulations — Prague 5, Czech Republic
[10.01.14]

Game Designer






Comments


Jeff Postma
profile image
Thanks for taking the time to write this up. I have also discovered that taking breaks sometimes increases my productivity greatly. Many breakthroughs happen when I'm walking around outside the building.

John Maurer
profile image
Nice write-up, I totally agree, but I'll confess to habitually breaking rules #1 & #4 :/

Sean Mann
profile image
Thanks for the article! It has Ben a reminder for me that I need to take breaks. I used to have a break reminder app but I got annoyed with it and uninstalled. What do you use?

Livio De La Cruz
profile image
I've always used this little program called TimeLeft (http://www.timeleft.info/) which runs on my PC. When it's time to take a break, it just makes a little ding that isn't too annoying. Although sometimes I miss it when I'm too focused, which sometimes makes me wish I used something more annoying, haha.

But the benefit to this over using a phone app is that sometimes my phone is just so slow and annoying that this is more convenient for me. Also I like to put the 15-minute break countdown into fullscreen mode as a way of (1) keeping me off the computer and (2) clearly communicating to my team that I'm on a timed break, so that it doesn't look like I'm just slacking off.

Jonathan Jennings
profile image
I think becoming a better debugger is a painful process, I have only gotten better at debugging by creating some truly awful bugs and then fixing them . now I know myself and the things i tend to overlook and when thing break I have a number of former experiences to recall when fixing THIS specific bug instance but yeah it took a while before I became a pretty decent debugger.

Great article otherwise so much of our profession is thinking so making sure we reduce how much information our brain has to hold and making sure we keep our bodies and minds healthy is critical I think .

Aaron Eastburn
profile image
Thanks for writing this up. They are all sound advice. Especially the debugging. The two best overlooked tips that I have noticed was to learn as many of the keyboard shortcuts as you could for the language/editor that you use. The other is to use a typing tutor to improve your typing accuracy. Both of those aren't necessarily programmer specific but it will help you write your code a lot faster... which will give you more time to debug. ;)

Livio De La Cruz
profile image
I agree! I was lucky enough to have had formal typing skills taught to me in middle school, and that's almost like learning how to breathe in this day and age.

I've never been too good at keyboard shortcuts, haha. I've always known the basic ones, but every time I hear about how helpful shortcuts are, I always overlook that piece of advice under the presumption that its just an insignificant self-optimization. It wasn't until a month or two ago that I started to use the "delete line" and "duplicate line" shortcuts, and now I can't imagine how I ever got around without them.

Ian Uniacke
profile image
I have one little tip:

Use the compiler where possible to avoid making bugs.

A good example that often happens when I program is that there is a virtual/abstract function that I want to change the name of for whatever reason (maybe I'm implementing another interface that conflicts with my method name). I could just try and remember really hard all the classes that inherit this function, or else I could do a search and fix them all up by hand, or even search and replace. The problem is that these are all prone to error. My solution is to use the compiler to enforce that all the functions are fixed. For example I would change the name of that function in a way that is obviously wrong (eg change OnUpdate to On______Update) AND make it pure virtual. Then I would compile the software and check every error it gives me. In my example the classes that are supposed to override the function I would fix up. I would put placeholder functions in classes that are not supposed to override. Once I have the errors all gone I would then rename my function to the proper name (eg OnUpdate) and compile again, renaming the methods that are supposed to be there and removing the methods that are not supposed to be there. Finally I would remove the pure virtuality.

That's a whole lot of explanation and the specific case is not really important. The point is that languages like C++ are very helpful at finding bugs for you, and you should learn the ways in which the compiler can be your friend.

Livio De La Cruz
profile image
That's a great tip! I love finding resourceful ways to solve problems like that.

Reminds me of one my favorite debugging techniques, which is to intentionally break things in hopes of luring out the bug that I'm looking for. Usually I have a theory on what's causing the bug, and sometimes the fastest way to test that theory is to break something else; and then if my theory about the bug is correct, then I usually have a specific way in which I'd expect that bug to interact with the newly broken system. This technique is usually useful for rather complicated bugs that emerge out of several complex interactions, rather than simple bugs that are contained in a single function.

Desmond Edem
profile image
Thanks man. I think my problem has always been debugging. But with these information, I know how to improve. Thanks once again!

Nick Weaver
profile image
Learn how to test: unit tests, acceptance tests, functional tests. Just let the computer do the repetitive chores.

Livio De La Cruz
profile image
That's a great tip. In my experience, it's been pretty hard for me to figure out how to fit unit tests into my game projects. But what I have done is built custom testing tools to fit the specific game that I'm working on. For instance, if I'm working on collision detection glitches, then it helps to have a system that can automatically run a bunch of different collision scenarios for you, rather than having to play the game and jump into walls hoping to cause the glitch again.

Patrick Horgan
profile image
Great article thanks for sharing :D

Karl Joyner
profile image
Great Article. Thanks for the tips :).

Juan Mora
profile image
Nice write-up. I agree with all, except #6. When it comes to writing comments embedded in the code, here we're following the idea of not writing a single comment ever. Instead, strictly following a couple of clean-code guidelines, we write code that explains itself better than any comment we could write.

Also, comments have the big disadvantage of becoming outdated (mismatched with the code) too easily and too quickly.

Livio De La Cruz
profile image
I've heard of that technique before, but it's always sounded a little daunting to me. I think at the end of the day, you just need some kind of mechanism that allows everyone on the team to understand the code, and maybe by banning comments, you force yourself to do other things like simply talking to your teammates more often, which might just have a better overall effect on your team. Either way, maybe I'll experiment with that approach one day.

Timothy Lochner
profile image
The caution I have with this technique (which in theory, I love) is that programmers will then not write comments, declare their code "self-documenting" and not realize that it's difficult to read and understand to someone who doesn't already have an intimate knowledge of what was written.

I have found a hybrid technique to work somewhat well. I use comments in header files, often because IDEs will take nearby comments and use them as tooltips when mousing over a function, class, or variable identifier.

Then, when some code just has to be unintuitive, I use comments to clarify. Working on existing projects and under a deadline, you often don't have the time to re-write everything the right way. You have to deal with legacy code and do some funky looking things. These comments clarify not obvious code. Again, this wouldn't be necessary in a perfect world, but it's quite imperfect.

The last thing I do, which could be a whole new item on the list, is I treat my comments as if it was the code itself. This helps prevent decaying comments. A way to help form this habit is to change the font color of comments to something like bright red, as if the comment was basically shouting at you. You will then be very careful about when you leave a comment.

Another idea is to write an extension to your IDE that highlights comments differently based on a mark-up. "//!" would become red and bold, "//?" would be yellow, while the normal case of "//" could become to the default comment color. This gets safely ignored by IDEs that don't pick up this syntax, but then allows you to at least communicate with your future self about the importance of the comment (ie, a caution/warning as opposed to an identifier description).

Johan Glysing
profile image
I also believe in code that explains itself over using comments.
However, there will be times when the code gets too complex to simply allow it to be explained easily such as algorithms. Thats where comments can be really valuable. Commenting for the sake of comments should, imho be avoided.

Ian Morrison
profile image
While I appreciate the intent and respect the goal of self-documenting code, I've personally been pretty frustrated working with code that's dogmatically avoided comments. Sure, the programmer might think that the code is self-explanatory, but that might not be true for someone coming to it for the first time, or for particularly complex or unintuitive tasks. More importantly, you miss out on a lot of opportunities to explain intent and design decisions. I can see a good argument for excising code that explains WHAT is being done, but no amount of code cleanliness standards can tell me WHY a specific design decision is being made, or why alternative approaches haven't been taken.

There's also a lot of convenient information that can be stored in comments, like explaining how a block of code, function or class fits into the broader design. Well written comments of this nature can save a programmer unfamiliar with the code an enormous amount of time that might otherwise be spent hunting down references around the codebase. You might be able to argue that this is what external documentation is for, but IMO the less external files I have to reference to understand a piece of code the faster I can get down to working with it.

I feel that it's important that comments are used to explain intent and context. I don't just need to be able to tell what the code does, I need to be able to understand your thought process for getting there!

Juan Mora
profile image
All fair comments.

I believe all those things, context, design decisions, the "why" of code, and everything else, can be expressed without using comments, but using the name of the related variables, methods, classes and namespaces.

I was one of those guys that used to write a lot of comments. But then I realized that every single idea that I provided with comments, can also be written as part of the names, in the code itself. It has been months since I started to avoid comments, and I haven't come across any idea or information that cannot be written in the names of the elements used in the code itself.

Of course, you have to follow certain rules. One of the keys is to make methods really, really small, so you have a lot of small methods, and a lot of room (each method's name) to give all kind of information.

Plus, the need of maintaining comments up-to-date (a tricky quest on its own) is totally gone.

Ian Morrison
profile image
How do you encode design decisions into variable and function names? "We chose implementation X instead of Y because Y has problems A,B, and C" or "we're not doing the normal thing here because otherwise X happens", for instance, seem like a difficult ideas to communicate in that format without without making the function name unwieldy.

Juan Mora
profile image
@Ian: Sure, the name will be longer than keeping the simplest possible name and make it go with a comment. I guess the way to go it's a dev team decision, whatever feels better for everyone.

For your example, I'd follow the naming "ImplementationWithoutProblemA". Sorry if it's not my best example, but it would be something like "class FormatterWithNullRefSupport", instead of a "class Formatter" that goes with a comment telling you should use this one if you want null reference support (instead of some other option).

Mark Verrey
profile image
I also try to use small classes with small functions and self-documenting names, but I find that while my individual units are self-explanatory, the overall architecture is often not. Unfortunately, there's no single place in the repository that you can put a comment and guarantee that the next person will see it, understand the pattern you're using, and follow suit. A quick ramp-up document might help, but it also needs to be short, otherwise nobody will have time to read it.

Documentation is simply a hard problem, and I don't think there's a single simple answer.

Ian Morrison
profile image
It absolutely is a "to each their own" sort of thing, though that'll never end the endless programmer holy wars over brace placement or tabs versus spaces! If you can get the whole team to buy in, though, it`s smooth sailing even with the strangest of programming styles!

I don`t think I`d ever be able to comfortably work with the style of function name you propose, though... that sounds like it would get very verbose, very quickly. If it works for you, though, more power to you. :)

Joe Program
profile image
As a designer, I also love it when programmers I'm working with have some design intuition. Sometimes the starting values I provide are way off. Programmers with design intuition understand the intent in the design, notice that my given values aren't good for the experience, and play with the numbers to get it to feel right before presenting it to me. It's so easy to get wrapped up in the code and task list, that it always stands out when a programmer considers the player experience too.

Chris Hattery
profile image
We like when designers understand a little coding as well. I've worked with designers who thought if they could mock something up in 2 hours, it should only take about 4 hours to program, and then couldn't understand why it would take so long or why the programmers would miss THEIR(the designers) deadlines.

George Menhal III
profile image
#1 on this list, in my opinion, should be "Learn to Work Well with Other People."

Because the reality of software development is, you're not going to be the lone ranger. Get used to that now and get really comfortable in your role as a member of a TEAM. Learn how to have respect for other people, and how to communicate very well.

That's my best programming advice. I was extremely disappointed and shocked when I first started programming professionally and discovered that I'd be knee deep in team assignments for the rest of my career.

Ian Morrison
profile image
This. Especially if you're a self-taught programmer it's easy to get caught off guard by just how much collaboration is involved in programming professionally. It's a problem for people new to game development generally, but I suspect that new programmers are more likely to have an individualistic, solve-all-my-problems-by-myself sort of mindset.

Livio De La Cruz
profile image
Oh man, that's so true. Even non-self-taught programmers probably went through a university program that didn't emphasize enough team projects.

There are a lot of unexpected problems that you run into when you program with others, such as resolving differences in coding/commenting style, mustering up the courage to confess that you really don't know what your teammates are talking about, making your code easier for others to understand, etc, etc... But there are also non-technical problems, such as how awkward or annoying you are to be around, how much you respect/disrespect your coworkers (especially those who are different from you), how understanding you are/aren't when it comes to other's problems, whether you tend to make people feel either stupid or comforted when they make mistakes, etc, etc...

I guess the main thing is to just remember that not everyone thinks like you and that there are tons of decisions that are simply a matter of taste, at the end of the day. For some reason, people who hang out a lot on the Internet like to think that their taste is TRUTH and that everyone else must be dumb. Tolerance for others and their ideas is definitely one of the top traits that I see in the people who I love to work with.

Chris Hattery
profile image
Thanks for this article. I think I might need to read it once a month to keep it in mind.

A program I use to help me reflect on my day's productivity is RescueTime.com. It's surprising to see how much time is wasted on things like facebook and email. (depending on what you're using each for)


none
 
Comment: