How comments get you through a code review

Code comments are a big point of discussion in software development. How and where to use comments. Or should you comment at all? Is the code not enough documentation if it is just written well enough? Here I would like to share my own experience with comments.

In the last months I had some code reviews where colleagues looked over my merge requests and gave me feedback. And it happened again and again that they asked questions why I do this or why I decided to go this way.
Often the decisions had a specific reason, for example because it was a customer requirement, a special case that had to be covered or the technology stack had to be kept small.

That is all metadata that would be tedious and time-consuming for reviewers to gather. And at some point, it is no longer a reviewer, it is a software developer 20 years from now who has to maintain the code and can not ask you questions any more . The same applies if you yourself adjust the code again some time later and can not remember your thoughts months ago. This often happens faster than you think. To highlight how fast details disappear here is a current example: This week I set up a new laptop because the old one had a hardware failure. I did all the steps only half a year ago. But without documentation, I would not have been able to reconstruct everything. And where the documentation was missing or incomplete, I had to invest effort to rediscover the required steps.


Here is an example of such a comment. In the code I want to compare if the mixer volume has changed after the user has made changes in the setup dialog.

var setup = await repository.LoadSetup(token);

var volumeOld = setup.Mixers.Contents.Select(mixer=>mixer.Volume).ToList();

setup = Setup.App.RunAsDialog(setup, configuration);

var volumeNew = setup.Mixers.Contents.Select(mixer=>mixer.Volume).ToList();
if (volumeNew == volumeOld)
ResizeToMixerVolume(setup, volumeOld);

Why do I save the volume in an additional variable instead of just writing the setup into a new variable in the third line? That would be much easier and more elegant. I change this quickly – and the program is broken.

This little comment would have prevented that and everyone would have understood why this way was chosen at the moment.

// We need to copy the volumes, because the original setup is partially mutated by the Setup App.
var volumeOld = setup.Mixers.Contents.Select(mixer=>mixer.Volume).ToList();

If you annotate such prominent places, where a lot of brain work has gone into, you make the code more comprehensible to everyone, including yourself. This way, a reviewer can understand the code without questions and the code becomes more maintainable in the long run.

Blog harvest, May 2010

Some noteworthy blog articles, harvested for May 2010. You’ll hear a lot about Java, a bit about Clojure, a fair share about Pair Programming and some thoughts about the advantage of employee exchange programs.

You can tell from the frequency of recent blog harvests that we are slightly overloaded with work at the moment. This is a rather preferred state to be in as a small contract development company, but everything not ultimately necessary is reduced during those phases. We consider blog reading as indispensable, but reporting the best of articles (our blog harvest) isn’t. So right now, we have a very long list of articles in our harvest barn. Here are some articles of the last two months:

  • Does Groovy Know You Are Seeing Clojure? – A real world story of learning Clojure, the Functional Programming language on top of the JVM. I can wholeheartly agree with the sentence “In the intervening 30 years since starting out on a TRS-80 Model 1 nothing has been more difficult in terms of solving even the most trivial of problems than learning Clojure.”, but in my case, it has been a little more than 15 years of real experience. After a year trying to “get” Clojure, I deferred it for more productive work.
  • Don’t return null; use a tail call – A blog entry about the billion-dollar-mistake (null pointers) and API design. It got inspired by Steve Freeman’s book “Growing Object-Oriented Software” (see next section for more content by Steve Freeman). The idea of “tail calls” or callbacks isn’t new or revolutionary, but widely underused. Personally, I found the idea of returning empty Iterables (as an abstract commonplace of Collections) useful in some scenarios.
  • Practical Styles of Pair Programming – First hand experiences of a pair programming enthusiast (Iwein Fuld). His scenarios seem familiar and the advices given reasonable. Reading the article sharpened my awareness about pair programming. There is only one complaint about the article from my side: Using headphones while programming doesn’t turn you into a zombie, it just eliminates the outer world for some time. That’s Alone Time, and it’s there for a reason, too.
  • Java1.6u18 and double array creation – A little story about flawed unit tests, recent java improvements and the value of nightly builds. Thanks for sharing this with the world, David Shay.
  • Do You Like Pain? – Jared Richardson shares his story and advice about getting used to the “pain” in any environment. I like the idea of the “prisoner swap” to identify pain points a lot. But from my own experience I can tell that the messenger might be muted by labelling him “not fully aware”.
  • Exploring Google GuavaGoogle Guava is the new Apache Commons. There are some neat features, though. Definitely worth the 20-minutes-read this article by Dan Lewis provides.
  • Java Post Mortem with Gilad Bracha – A post mortem should only be done on “dead” people/projects. So the title alone is a harsh statement. But the summary of the talk contains some valid points and a lot of opinions to think about. I particularly like the term “cottage industry” for DI framework vendors.

Next comes the video section of this blog harvest. I’ve found the time invested in these talks worthwhile:

  • Threading is not a model (35min) – Joe Gregorio presents the lack of advanced multiprocessing tools in most programming languages. His talk covers a lot more than just that and gives some appetizers on Python. The solicited lack of MP support was my reason to learn Clojure (see first entry in the list above).
  • Sustainable Test-Driven Development (55min) – Steve Freeman gives a whole bunch of advanced tips to write unit tests. The talk is given from the TDD/BDD point of view, but mostly applies to unit tests in general. You should be familiar with JUnit to fully understand this talk.

And at last, there is a tool I want to present you (this kind of resembles the fun section, too):

  • Dollar – An experimental java API that shows how much you can bend the java syntax to suit your personal taste. Through inspiration by this project I’ve come to some unique ways to make my code more expressive – without using funny signs. Thanks to Davide Angelocola for his unique approach.

Blog harvest, March/Easter 2010

Some noteworthy blog articles, harvested for March/Easter 2010. You’ll hear a lot about common software bugs, Java, inappropriate hiring procedures and Scala. If you ever wanted to know about the Fussy Bird in Scala, this blog post is for you, too.

Easter times means springtime, an hour stolen by the daylight saving time, rapidly changing weather and the first days without gloves (I catch chillblains very quick. There isn’t an adequate word for them in the german language, so I couldn’t name it for years). We are looking forward for a very hot summer, not only with the weather. But now, let’s talk about software.

  • Top 10 Web Software Application Security Risks – The OWASP community has released their current list of web programmer gotchas. There is nothing to add but “don’t try this at work, kids!”. For a broader audience, there’s the updated “Top 25 Most Dangerous Programming Errors” from the Common Weakness Enumeration project.
  • The 10 most common mistakes made in software development – Another top list with developer mistakes, written by Peter Horsten from GOYELLO IT Services. This one isn’t too code centric and doesn’t provide many solutions, but there is much wisdom in top 9 and 10.
  • I Have No Talent – There is a saying that open source development will make you humble, but John Nunemaker takes it to an extreme. He speaks true words. My favourite phrase is the last one, saying that he doesn’t compare himself to others, but to his own progress. If only everybody would do.
  • Why I love everything you hate about Java – An interesting blog entry by Nick Kallen. He takes a stand for the “bloated” middle-layer in (java) code. The post tends to be a long read, but I found it worthwile. The one thing I hate about Java is the slow progress in recent years.
  • Why I dropped Scala in favor of Java? – While you might argue about the universal importance of Subhash Chandran’s reasoning, it’s still valid. Combined with the previous blog harvest entry, there’s a pattern to be discovered: the grass isn’t always greener on the other side. But you have to change sides to see it.
  • NIO.2 : The new Path API in Java 7 – Java makes slow progress in recent years, but there is progress to be seen. The Path API is something we could have used years earlier. The DirectoryStream and WatchService are two functionalities you couldn’t easily build on your own yet.
  • Ant 1.8 Scanning Leaves 1.7.1 in the Dust – If you are using Ant, you can regain performance with just an upgrade. And you will find the other new features (like lexically scoped properties) really useful.

This was the more serious part of this harvesting. Let’s read some articles that share their message in a lighter way:

Finally, I want to introduce a “interesting tool” section. Each new harvest should present a framework/product/project I found interesting enough to tell you about it:

  • op4j – It calls itself a developer happiness tool. You may call it a stress test for static imports, collection kung-fu or fluency madness. But nevertheless, it’s fun to apply it to your boring old data structures.

P.S.: No easter egg is to be found in this posting.

Blog harvest, February 2010

Some noteworthy blog articles, harvested for February 2010. If you ever asked yourself about the personality of your web framework, you’ll find the link to the answer here.

After the move to the new office is nearly complete, work begins to normalize again. Here is the February blog harvest with a little more entries, as I wasn’t unable to read other blogs, but to write on our own blog. There are many fun articles this time that I found share-worthy, perhaps because they made me laugh even in harder times.

This was the more serious part of this harvesting. Let’s read some articles that share their message in a lighter way:

  • What kind of woman would your web framework be? – If you ever have to sell a new hot (web) framework to management, why not take this plausible approach? At least they could relate to what you are talking about.
  • It’s Not the Recession, You Just Suck – Ouch! That hurt. This is a wake-up call for everybody who likes to blame it on higher means. And it reminds me to hurry up with this blog entry and get back to work.
  • I test therefore I log bugs – Ever tried to explain “programming” to your grandparents? You’ll end in esoterics (“teaching machines to have dreams”) or in obviousnesses. This is a story about consensus on the latter.

This blog harvest closes with a video:

  • Uncle Bob on Software Craftsmanship – Much of what Bob Martin says has truth in it, but for me the last two minutes are the most explicit and rewarding. By the way, Uncle Bob looks good in the T-Shirt (I always feared it would be teared, regarding the sounds when he stretches), but needs to switch his cell phone off.

Blog harvest, January 2010

Some noteworthy blog articles, harvested for January 2010. Don’t miss the worst gadget gallery!

Welcome to the new year. We started late to work again this year and will collect some overtime in the next weeks as we are in the process of moving to a new office. This might impact the additional blog entries, so here is a quick blog harvest. Don’t miss the anti-gadget gallery at the end – but beware, it will make you laugh out loud, so don’t read it at work (unless you are supposed to have fun at work).

  • Reasons to Use Google Collections – Recently, the google collections library went gold. It’s a really nice collection of… collections. If you haven’t met it yet, do it now. You might read James Sugrue’s teaser alongside.
  • How Programming Books Promote Code Smells – Finally, somebody shares my opinion on “code examples crippled for brevity”. I got disgusted by some java books because their code examples were so bad, it hurt. The situation eases a lot with the availability of “real” code in open source projects that you can read as recompense.
  • Test-Driven Teaching! – Another problem with bad code examples is to avoid them in live examples (like in lectures). Here is an interesting article by Peter Karich presenting the idea of integrating test code in your lectures. I’ll see if my students like the idea.
  • A performance tuning story – The best stories are real stories. This story has all that’s needed: a mysterious effect at the beginning, fast-paced action in the middle and an open end. The X files weren’t as thrilling as this one.
  • Maven and Ant guys: you’ll never agree. On anything. Period. Deal with it! – What would we do if we couldn’t join an eternal flame war at surf time? You can join on one side (there are always two sides, seldom more!) or stand in between and pick on both. Lieven Doclo chose the Maven side of builds.
  • Maven Mythbusters – The most prominent maven myths get busted by John Ferguson Smart to end the flame war mentioned above once and for all (or at least take out some misinformation). I’ve linked to the first busted myth, you’ll have no trouble finding the other(s). Read the comments, too!
  • The Top 10 Posts of this Blog Over the Years – Stephan Schmidt’s blog “Code Monkeyism” is a regular link target in my harvests. When he harvested his own blog for the most popular entries, I couldn’t resist linking him once more. Maybe this is called meta-harvesting.

This was the article side of this harvesting. Let’s continue to have fun by sliding through the gallery and then… sliding through your repository:

  • Gizmodo’s Worst Gadget Gallery – Oh yes, ten years full of technological crap, complete with pictures and a short description. If you spend 30 seconds on each gadget, you’re in for half an hour pure fun. My favorites are the DeathStar for personal reference (we lost 7 of 9) and the Eye-Track for its funny description.
  • Mining your source code repository – Part 1 – Yes, all your legacy repositories are still there. Discover the archeologist in yourself and perform some data mining on them. This article may be the starting point for your new career.

Blog harvest, Christmas 2009

Some noteworthy blog articles, harvested for Christmas 2009. Merry Christmas, everyone.

This is the Christmas special edition of our blog harvest. Granted, there is nothing really “special” about it other than the release date. But some of the collected articles are too good to wait until 2010. Be sure to check out the video link at the end, it’s a great presentation.

  • 7 Computer Books I Enjoyed in 2009 – Even if it isn’t my list, I’m glad for this summary of enjoyable books by Freddy Daoud. The first entry on the list is my current programming language book, so I might be somewhat biased.
  • For a fistful of dollars: quantifying the benefits of TDD – A very balanced article about test driven development, backed up by studies. What do we need more? Oh yes, literature! See the links and the last paragraph for this. And grant John Ferguson Smart some self-marketing for his wonderful posting.
  • Remote Pair Programming – Pair programming, like TDD, is a valueable practice. But pairing always requires physical presence. Keith Brophy explored the possibilities of modern software to nullify this requirement. The comments, mentioning Crucible, are also noteworthy.
  • Java 7 chapter 1: The Virtual Machine – The last few years, there was this announceware, nicknamed “Dolphin”. Every few months, blog entries pop up to tell us about the latest and greatest feature of Java 7. Harals Kl. wrote a mini-series that sums it up really nice and doesn’t conceal the dropped features like the Swing Application Framework. Be sure to read all articles of the series.
  • Learn to Let Go: How Success Killed Duke Nukem – While the context to place this article right here is purely coincidential and this isn’t exactly hard computer science, it’s a worthwhile story about a failed project (and the most successful vaporware ever). We grew up with Duke Nukem 3D, it’s a hard loss for us (ok, we will get over it).
  • The Law of Unintended Consequences – This article talks about coincidence, too. Justin Etheredge describes sources of negative side-effects and what software developers can do against it. The introductory example of heatless traffic lights won’t do for developers, because we all know the joke: “How many software developers do you need to change a light bulb?” (*).
  • A Pictorial Guide to avoiding Camera Loss – As this already tends to be humorous: Andrew McDonald talks about another hardware problem – losing a digital camera and how to regain it. Let me warn you about the 16th picture of the guide.

This was the article side of this harvesting. Let’s continue to have fun by watching the promised video and reading about a real misadventurer:

Thank you for reading through this last blog harvest in 2009. See you again in 2010!

(*) “How many software developers do you need to change a light bulb?”: None, it’s a hardware problem.

Blog harvest, December 2009

Some noteworthy blog articles, harvested for early December 2009

Today’s blog harvest spans a lot of topics that i’ve found noteworthy in the last weeks. As an added bonus, there’s a watchworthy video link at the end. I hope you enjoy reading the articles as much as I did. If you have thoughts one the articles, feel free to comment them here.

This was the article side of this harvesting. Let’s have some fun by watching a video and relieving our conscience:

  • Living with 1000 Open Source Projects – It might get crowded on your disk! Nic Williams shares his secrets of mastering open source heavy lifting. The video runs a short half hour and has its funniest minute between 11:20 and 12:20. Brilliant!
  • The Bad Code Offset – Guilty of writing bad code? Well, remember the last entry of the list above? You’ve probably created a new job. If not, you can find absolution by buying some “Bad Code Offsets”. Think of it as the Carbon offset of the software industry.

Blog harvest: Metaprogramming in Ruby,Hudson builds IPhone apps, Git workflow, Podcasting Equipment and Marketing

Four blog posts:

  • Python decorators in Ruby – You can do amazing things in a language like Ruby or Lisp with a decent meta programming facility, here a language feature to annotate methods which needed a syntax change in Python is build inside of Ruby without any change to the language spec.
  • How to automate your IPhone app builds with Hudson – Another domain in which the popular CI Hudson helps: building your IPhone apps.
  • A Git workflow for agile teams – As distributed version control systems get more and more attention and are used by more teams you have to think about your utilisation of them.
  • Podcasting Equipment Guide – A bit offtopic but interesting nonetheless: if you want to do your own podcasts which equipment is right for you.

and a video:

Blog harvest, October II

Some interesting blog articles, harvested for late October 2009

harvest64A great way to stay up to date with current musings and hypes of our industry is to follow other people’s blogs. We do this regularly – everybody scans his RSS feeds and roams the internet. But to have a pool of shared knowledge, we pick our favorite recent blog articles and usually write an email titled “blog harvest” to the rest of the company.

Then, the idea came up to replace the internal email by a public blog post. So here it is, the first entry of a new category called “blog harvests”. You’ll read more harvests in the future. They will be categorized and tagged appropriate and have the harvest icon nearby.

Second Blog harvest for October 2009

There are four main blog entries I want to share:

  • 8 Signs your code sucks – Let’s assume we all read Martin Fowler’s classic “Refactoring” book, then these eight signs are a mere starter. But as the follow-up post indicates, it got quite a few people started and upset for the “comments are code smells” line. Well, we heartfully agree with the premise that comments are clutter and code should be the comment. /* TODO: Add a joke using comments here */
  • ORMs are a thing of the past – Another opinion that might get in the way of hibernate fanboys. We’ve had our share of hibernate “experiences”. It’s a useful tool if you know how to use it – and when not to. Replies followed instantly, here are two noteworthy ones by Scot Mcphee and by Jens Schauder.
  • The Case for Clojure – Clojure is functional programming on the Java VM (think LISP). Stay tuned for our own book review on this topic. You can argue that Clojure isn’t pure, though.
  • Bad Programmers Create Jobs – As is already is a controversy harvesting, lets add some more, written by Mohammad Azam. Side note: Half of our work was initially created by “bad” programmers, so I think Mohammad hit the nail on the head. And remember that you’ve produced legacy code today.

Then there is a bit of (future) knowledge you shouldn’t miss:

That’s it for now. My harvest format has changed for the blog, i’ll evolve it further in the next months, Thanks for your attention, stay tuned.