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

[Tim Penhey]

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

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.

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.

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.

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.

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.

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