Thursday, June 6, 2013

State of the Art - Don't Comment Your Code

I was listening to a Java Posse podcast this morning, and the hosts were discussing the pros and cons of putting comments in your code.   I consider myself a software craftsman, and a big part of that involves writing readable code.  I have done it often enough to know that good code really doesn't need comments, and by that I mean any non-Javadoc comments.  (And only your API code should have those.)

The fact that the Java Posse guys seemed unaware of this as a practice surprised me, so I did a little digging with the expectation that this "obviously beneficial" practice was being used by most, but not all developers.  I was surprised to find a number of fools who were dismissive of the idea, in addition to a number of obviously intelligent people who agreed with me.  Apparently this is not yet a mainstream concept.

I have worked at a lot of places, and the best, most maintainable, easiest-to-change code I have ever seen was all written at my current workplace where "no comments!" is the norm.  Really top-notch programmers can certainly still create excellent software with large methods, confusing method and variable names, and other code smells.  Mere mortals will struggle to change such code, though.

So why, if this is so obviously beneficial, is it not standard practice across the board to avoid comments whenever possible?  I have a few ideas, based on my experience in different software shops:

  • Some codebases are changed very slowly or simply have the expectation that any change will be time-consuming and expensive.  Such code is probably internal-only.  In this case it would be less obvious that the code is hard to change.
  • Many programmers don't consider themselves professionals, and don't try to keep their skills up-to-date with constant self-education and practice.
  • I'm wrong.
While the third bullet point has happened before, I don't think so in this case.  I suspect rather strongly that the second bullet is the most likely one.  It's easy to let your skills and knowledge go stale, so that's what most people do.

If that describes you, beware!  You're not likely to remain employed in this brave new world if you're not competitive.

Saturday, March 2, 2013

Google does 20%, we do 10%

I work at Cengage Learning (my views are my own, they don't represent the company, etc, etc, etc), and we recently started giving developers the option to make use of  "The Cengage 10".  This means that we can use 10% of our work time for a project that we're passionate about.

The idea is to drive innovation and make it a better workplace.  So far, I think we're successful at both goals, but it may be a little bit early to tell on the second one.  Doing this hasn't impacted delivery dates for normal business-driven projects.

We did put a couple of restrictions around it:

  • If your team room really needs you (broken build, release problems, etc.), don't leave to work on your side project.
  • You should work on a project with at least one other person.
  • A "project" doesn't have to provide direct business value - it can be learning a new technology.
This works pretty well because we hired people who enjoy their work and don't need much supervision.  Treating good developers like losers who won't do any work without constant monitoring is a great way to get the good ones to leave.  (Until you're left with losers who won't do any work without constant monitoring.)

And yes, the idea came from the way Google treats its developers.

Friday, January 18, 2013

Expert Searching With Google


I found this site on "Power Searching with Google".  It describes how to get the most out of a google search. For 90% of my searching, a quick & dirty search (which is what I usually do) should be fine.  But that other 10% probably represents half of the time I spend trying to find things.  My usual strategy is to keep banging away & try new search terms.  The course recommends doing exactly that, but here are a few tips that I think will save a LOT of time for more specific searches:
  • When searching for images, use the "search tools" and choose a color.  Black & white, gray, white or black in particular are useful for finding diagrams.
  • Google scholar is great for finding authoritative search results.  
    • I think that it is similar to searching with site:edu, plus some other academic sources.  
    • Note the legal search results - court opinions are much clearer that I would have believed (and a lot more wordy).
  • Site: is useful if you want to restrict to a particular site or subset of sites. 
    • Restricting to site:gov would only give you official US government sites.  (You can use go.uk, go.fr, etc. to search other country govt sites).
    • Restricting site:edu will only give you US educational institutions.  Useful if you want a more collegiate take on the subject.
  • Filetype: can be useful if you want just a .csv or .klm (Google Earth) or a particular format.
    • filetype:pdf might be worthwhile if you want a document that covers the topic.
    • Combining site:edu filetype:pdf would (I think) restrict your search to something like "Academic papers on this subject", as opposed to abstracts or simple web pages.
  • This page has a pretty good summary of the search features, most of which are automatic.
You can get as much (or more) out of Google search simply by exploring the interface and trying everything that they have available.  They have put a lot of thought and effort into it.

Friday, January 4, 2013

The Roman Numeral Kata

I've been pulling together a kata based on converting Roman numerals.  The idea is that after having people refactor this one to something relatively clean, they can test drive a different design.

I haven't settled on a good design just yet, though.  The concepts I want to drive home are:

  • Excellent naming
  • Small Modules
  • Low Complexity
  • Single Responsibility
Does anyone have a favorite problem space, or a solution to the Roman numeral conversion problem that really drives these home?