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

[Andrew Wilkins]

Decent read so far. Lots of reasonable ideas (obvious ideas, even!), though
some were a bit too dogmatic for me to swallow whole.

I think for me the most important sections were (in chapter 2):
 - Use Intention Revealing Names,
 - Add Meaningful Context, and
 - (to a lesser degree) Don't Add Gratuitous Context

"Use Solution Domain Names" before "Use Problem Domain Names" also
resonates with me. Juju hasn't been too bad about this, but I've worked on
things before where it's taken a lot of effort to understand things simply
because the names were in the problem domain when they didn't need to be.
This makes it difficult to ramp up. I think this is especially important to
juju, since it's Open Source. If we want to encourage contributions, then
it's important to minimise the barriers to entry.

More inline...

On Tue, Sep 17, 2013 at 12:04 PM, Tim Penhey <tim.penhey at canonical.com>wrote:

> Hi folks,
>
> Rereading this book reminded me how good I found it.  I went through and
> picked out some bits that I think that should be repeated.
>
> Small things matter.  There has been a joke amongst some Canonical folks
> for a while that the company name should be "Pedantical".
>

Better to be Pedantical than Lackadaisical ;)


> I'm a big supporter of the "boy scout principle", leave the code cleaner
> than you found it. This doesn't mean you have to clean up the entire
> file, or every place where X happens. Many incremental changes are
> better than being put off starting because you know you'll be asked to
> fix it everywhere.
>

Absolutely agree. I do think there ought to be discussion when changing
style and what not, though. In my former life, there was an individual I
worked with who loved to change all the code he ever touched to his own
unique style (I won't reproduce it here to protect the innocent - save to
say it was unusual). We have gofmt of course, but I think this extends to
other things. Naming, of course.


> Learning to write clean code is /hard work/.  You won't get it straight
> away, just like reading how to ride a bike doesn't mean you won't fall off.
>
> I loved Ron Jeffries comment:
>     When the same thing is done over and over, it's a sign that there is
> an idea in our mind that is not well represented in the code.  I try to
> figure out what it is. Then I try to express that idea more clearly.
>
> I feel that we have a lot of duplication in our codebase for this
> reason.  Something that we can work on in an incremental manner I believe.
>

I haven't really noticed it being a problem yet, but then I haven't poked
my nose into all the code.

I don't think many people will disagree that deduplication of code is a bad
idea in general. However, as with database denormalisation, there are
exceptions to the rule. If in the process of deduplicating you make things
considerably more complicated to handle the genericity, then what have you
gained?

A few statements relating to Ward Cunningham were wonderful too:
>     Ward expects that when you read clean code you won't be surprised at
> all. Indeed, you won't even expend much effort. You will read it, and it
> will be pretty much what you expected.
>
> and
>     He says that beautiful code makes the language look like it was made
> for the problem! ... It is not the language that makes programs appear
> simple. It is the programmer that makes the language appear simple.
>
> For naming things, I found one line particularly interesting:
>   Info and Data are indistinct nose words like a, an and the.
>

In general I agree, however there was one thing that I didn't really agree
with in the book, and that's the difference between Customer and
CustomerInfo (I think that was the example). One is an entity, and one is
information about *about* that entity. The information doesn't necessarily
belong to that customer.


> I'd put State in that list too for the double banger state.Info.


> On the "Use Searchable Names" section I found one indicator as to why
> our estimations are off.
>   int realDaysPerIdealDay = 4;
>
> Another area where I think juju could use some additional thinking is
> "Pick One Word per Concept".  We reuse things too often, and have vague
> or unrelated names for some things.  Think "Environment".
>
> I won't go into my rant about single character variables again, as that
> is already on the list.
>

There is an apology for single character variables in the book: "The length
of a name should correspond to the size of its scope."
This essentially amounts to the article that Nate linked to (
http://research.swtch.com/names). This resonates well with me.

Length aside, I think it's very important to consider context when naming
things, and whether that context is available and obvious to a consumer.
I've come across parts of the juju code where function names make sense
only when you see them in the function's source file. That's not helpful
when you're looking at it from a caller's perspective.

One point is though, I know that some people have a more automatic
> translation of ctx to context than others.  For be I see the letters
> "see tee ecks" and it requires more cognitive mapping to get to context,
> whereas the word requires no mapping.  We don't want to write code that
> only people who think like us will understand.
>

That's fair. The difficulty is of course coming to a consensus. What's too
short? What's too long? What's an obvious abbreviation, and what's not?
These are all subjective.

In the book, I spotted a recommended variable name that started "addr",
rather than "address". In our own code we have "env" and "environ" where we
could easily go all out and write "environment".

Finally, I think everyone should agree with this:
>   Our goal, as authors, is to make our code as easy as possible to
> understand.
>
> How about your comments?
>
> Tim
>
> --
> Juju-dev mailing list
> Juju-dev at lists.ubuntu.com
> Modify settings or unsubscribe at:
> https://lists.ubuntu.com/mailman/listinfo/juju-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju-dev/attachments/20130917/a91c115f/attachment-0001.html>