Slow Down to Go Faster | Hacker News Reader

Slow Down to Go Faster

fuelyourcoding.com

44 pointssant0sk113 comments

I am always amazed how few developers document their code.

I always hear:

"I write code that is easy to read" - Great but well written code can't... tell you why it was done this way, what it is actually supposed to do, how people should use it, how people shouldn't use it.

"I don't have time" - When is a developers time constrained by typing? Unless you type one word a minute you have time type create documentation.

Documentation is even helpful when creating the code. As ideas or thoughts change medium... from brain to paper or to sentence form. I see the problem differently, which gives them better understanding before wasting time creating something that isn't going to work.

Documentation is also helpful for two other people: Those who are not you and your slightly older self.

I'm always amazed how few developers _read_ documentation of the code if it's there. I've had multiple instances where I comment a section of code explaining why it's very important that a certain thing be done just this way (or that a certain thing _not_ be done), only to have someone else come through a couple months later and break things by making exactly the change that the comment said not to do.

did you have a test for it?

In some cases, yes. More frequently this sort of thing has been performance issues (comment reading something like "don't do X here, or else it interacts with Y in a way that kills performance of the whole application"). Testing for performance regressions can catch stuff like this, but since that's not typically done for every commit, you can end up having to do significant forensics or trawl through hundreds of commits to find the cause.

I'm going to go against the grain and say that I don't feel one should spend much time naming things. I suppose that's just my style of doing things. There's actually a hacker koan about this[1]:

A cocky novice once said to Stallman: “I can guess why the editor is called Emacs, but why is the justifier called Bolio?”. Stallman replied forcefully, “Names are but names, ‘Emack & Bolio's’ is the name of a popular ice cream shop in Boston-town. Neither of these men had anything to do with the software.” His question answered, yet unanswered, the novice turned to go, but Stallman called to him, “Neither Emack nor Bolio had anything to do with the ice cream shop, either."

Now, I'm not saying that one name variables and whatnot whatever obscure name first comes to mind. It's just that I'm not the kind of person who spends hours trying to think of just the right name. I will spend hours thinking about the appropriate architecture and how things fit together though. I find that once I've done that, the names become far less an issue.

[1] http://en.wikipedia.org/wiki/Hacker_koan#Emacs_and_Bolio

re: naming things.

Please have objects be nouns and methods be verbs. Please done have a class named "buildLetter" or "generateEmail" - it's confusing to read.

At least to me.

Perhaps I'm alone in that? I run in to enough "objects named as verbs" I'm sort of beginning to wonder if I'm alone in this thinking.

Only thing I am on the fence about is "methods be verbs", unless your language differentiates between methods and properties. The exception in my mind was the classic Point.x, where x is a method for accessing the value of an internal x.

Note that some languages, such as perl, understand whether you are setting or getting by the surrounding syntax:

   my $x = $point->x;   # get the value of x
   $point->x(100);      # set the value of x

"point" can be a verb too. :-)

Just today I renamed a method someone named "showButton" because I thought

  result = showButton()

was a call that showed the button and returned a boolean result. In reality it just returned a boolean based on if it was configured to show a button. The new name: "shouldShowButton"

But then I got to thinking… well… maybe I'm suggesting that the button should be shown…

There's something to be said for context.

I usually write out a bunch of names without thinking to hard about them and then try to read them. In this instance, given that you've already had showButton and shouldShowButton i'd probably look at:

  result = buttonShown()
  result = buttonVisible()
  result = buttonIsVisible()
  result = visibleButton()
  result = !buttonHidden()

To a lot of programmers this would seem like a waste of time, but I'm with the article's author (and, I'd hope, other HN readers) in that it's time well spent.

[Redacted] Misread your post.

What would confuse me about generateEmail is that on the surface without even looking at the code I would wonder if it built the e-mail body itself or sent out an e-mail or both.

Do yourself a favor: slow down & put some thought into naming things. Future-you will reap the benefits.

Do yourself a bigger favor: Go back and re-read all 4 paragraphs in the section "Naming Things". This is solid gold and one of the most overlooked aspects of building good code.

I have slowed down many times and named things (variables, function names, labels, etc.) exactly the way I wanted. Then came back 2 days later, unable to understand what I had just written. Because the names were still not good enough.

Naming things can be an iterative process. And it's not a waste of time. Coming up with just the right name is hard, but it really makes you think about what you're doing, how you're doing it, and why. These are the things we should be spending time on.

This reminds me of Harry Beckwith, the marketing consultant from the east coast who called on clients in California. On the plane trip home, he worked on coming up with just the right name for his client. Invariably, he came up with the perfect name over Lake Tahoe. The next day, he reviewed this name and realized that it was a good first try, but still not right. He came up with the term "Lake Tahoe name" to remind himself that he still wasn't done.

Don't leave Lake Tahoe names in your code. You're not done yet.

[Harry Beckwith reference: http://search.barnesandnoble.com/What-Clients-Love/Harry-Bec...]

I put a lot of time into naming things correctly. If I can't find a name that I like I will use what is foremost in my head, comment the function of the variable, and move on.

Reply on news.ycombinator.com