
Slow Down to Go Faster - sant0sk1
http://fuelyourcoding.com/slow-down-to-go-faster/
======
bbuffone
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.

~~~
kscaldef
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.

~~~
jshen
did you have a test for it?

~~~
kscaldef
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.

------
j_baker
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>

------
mgkimsal
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.

~~~
Xurinos
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

~~~
po
"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.

~~~
smcl
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.

------
edw519
_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...](http://search.barnesandnoble.com/What-Clients-Love/Harry-
Beckwith/e/9780446527552)]

------
atomical
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.

