Clean Code: Intro, Clean Code and Meaningful Names (up to the end of chapter 2)

[Tim Penhey]

On 26/09/13 22:30, Nate Finch wrote:
> Sorry, I've had this half typed out for like a week and a half.
> 
> A general overview - I was actually really excited about the book. I try
> to stress in words and actions that readable code is so much more
> important than almost anything else. However, I find that the author's
> definition and mine diverge somewhat. I was also really unhappy that he
> focuses so closely on java without even an attempt to make his
> statements apply to multiple languages. Obviously, we can still do the
> translation ourselves, but it seems like he should have just called it
> "Clean Java Code"

Well, I think that the principles generally carry across, but yes, I
also tire at reading lots of Java.  I stopped working in it for a reason.

> People complain about single letter variable names, but if the function
> is only 10 lines long, does it really matter? You can see s :=
> thing.State()  ... so you know it's a state.  Does it make it clearer to
> call it state when you see it used 2 lines below?  I don't think so.
>  That being said, it's fine to call it state, too.  It's just when you
> call it thingStateForReviewLater that it actually makes the code harder
> to read when it's used in more than trivial expressions.

I've come to expect single character variables for the function
receivers, and I don't object as much to single character variables used
very closely to the declaration, but if I have to scroll to find it, I
take that as bad.

For example:

  defer l.r.Close()

l is the function receiver, but what is r?

ctx.ru.Settings()

Again, short names used inside structures.

> One of the things I like a lot is the idea of using the context of how a
> function will be called to avoid extraneous words in the function name.
>  This works especially well in Go, since you call functions prepended by
> the name of the package, so like container.Insert(ball), instead of
> container.InsertBallIntoContainer(ball).

While this is mostly good, there are issues where it becomes problematic.

For example importing "launchpad.net/juju-core/tools", now we can't have
a variable called "tools" because it clashes with the package.  We have
a number of packages where we bastardize the variable name to avoid
clashes with the package name.

Alternatively you can change the name of the package locally by giving a
name to the import, but then you lose some of the context for the
functions if you rely on the package name to provide the understanding.

Tim