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

Thu Sep 19 16:57:32 UTC 2013

Great discussion!

I think there does need to be a level of pragmatism -- clean code is a
means to an end. It reduces the cost of delivering features, and therefore
makes it easier for us to achieve all our real goals.

But as Gustavo correctly points out, the ultimate goal is happy and
productive users who are getting real value from our work.

Which leads me back to the old "technical debt" metaphor, but not in the
standard "avoid technical debt at all costs" way of looking at it. Just
like financial debt, I think there is a difference between "good technical
debt" and "bad technical debt."  And the fundamental character of that
difference is the same:   Investments that have a risk adjusted ROI higher
than the Cost of Debt are good, and those that don't are bad.

Less, abstractly: Compromises on code quality to get to market, acquire a
critical mass of users, or otherwise to invest in the success of the
product/project are OK -- but just like real debt, you must careful to
weigh potential gains against the costs.

*Long, concrete, and informative -- but ultimately skippable example*

A R&D group with ten development teams with four devs each has pile of
product ideas that all seem to have equal merit. To vastly oversimplify the
costs: Building any one of those products "the right way" will cost about 3
team months of effort.  But hacking something together in the ugliest way
possible (bad tests, no continuous integration, quick and dirty technology
choices that don't scale, etc) will cost a quarter of that or about 3
weeks. And because of all the debt that needs to be paid down it takes the
original three months, plus an extra fifty percent longer to clean up.

So, all of that debt acquisition means what would have taken 3 months, now
takes 6.

For one team working on one project doing it right the first time is almost
certainly a win -- you get to avoid three months of waste, and you only
sacrifice 6 weeks of potential revenue on a buggy product.  For some small
percentage of products, that 6 weeks of revenue might pay of the costs, or
there might be a strategic reason why you need that time to market, but the
general rule for optimizing team productivity would be in favor of doing it
right.

But, if you take into account the fact that 90% of new projects fail to
achieve product-market-fit, and the company can re-allocate the development
effort that would have gone into the other 9 projects after doing the six
week demo, the cost benefit scale tilts the other way.  You now have 9
teams saving 6 weeks for a total savings of 10.5 "team months," put against
one team that "wasted" just 3 months.   And they can therefore test an
additional 7 product ideas, possibly finding a second "successful" product.

It's hard and probably impossible to quantify all of the risks, potential
rewards, and costs involved in these trade-offs, and it's good for us to
have a shared view on all of this in the "big decisions" that the project
faces.   But

*Rules of Thumb for Code Cleanup*

But, for everyday work, I'm also very aware that we need some shortcuts,
and rules of thumb. We can't make every single code cleanup decision by
trying to weigh all the costs and all the benefits.

Given that Juju is a product that already has real users, and has grown to
a significant size I would like to propose a set of rules of thumb that
make sense to me:

   -  knowingly acquiring significant (as in will cost a lot later)
   technical debt a bad idea and new debt should be an exception rather than
   the rule.
   -  we need to pay down debts* when we see that they are starting to cost
   something* in terms of further development work.

The second rule might need a bit of unpacking it means:

   - doing drive-by cleanup as we write new features,
   - refactoring and de-duplicating existing code to remove impediments to
   progress as needed to build new features

But it does not mean:

   - going through a massive cleanup effort to  we fix every naming
   inconsistency
   - finding and purging every possible bit of code duplication everywhere
   - finding the perfect solution to every question of where to draw the
   lines of abstraction, and then going back and fixing all the code to match
   that ideal abstraction layer

These are just rules of thumb that have helped me and others on my team
work a much bigger, much, much, much messier codebase littered debt
land-mines.  And while I think they apply here, I don't know if they are
formulated in the most effective way for our team or our project, so I'm
just throwing them out for your feedback.

*Back to the book*

Reading "Clean Code" could be about a lot of things. It could be about
forging a team with a shared understanding of code quality. That would be
amazing and valuable. Or it could be about double guessing every old
decision, and trying to fix everything that ever "went wrong" up to this
point in the project -- which would be painful and a complete waste.

My hope is that this book helps us all grow a shared vocabulary of code
quality, and to improve the speed and fluency with which we can handle code
quality questions.

And my belief is that if we as a team continues to clean up problems as
they come across them, and works together to learn new things, and develops
the ability to communicate more effectively about the problems we face --
the will see increases in velocity/capacity and all of our old problems get
easier and easier to solve. This is akin to inflation making all your old
debts easier to pay off -- but unlike inflation it also makes everything
new easier to buy too.

So, to sum up my view on all of this: growing the capacity of the team is
my number one goal, because it makes *everything* easier in the future.

Oh, and it's way more fun when work flows smoothly, everybody has shared
understanding, and amazing things happen. We at the center of a huge change
in the world, and we are delivering amazing new stuff on a regular basis,
how cool is that!

--Mark

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

> On 18/09/13 07:33, Gustavo Niemeyer wrote:
> > This isn't, by all means, to suggest that we should stop caring about
> > the quality of our code base. I'm all for improving variable names,
> > type names, and whatever else, as people who actually worked with me
> > can confirm. It's rather just a small reminder that perfect code comes
> > second to having a relevant product.
>
> I both agree and disagree :-)
>
> Having perfect code and a useless product is pointless unless the code
> is itself the goal, which it almost always isn't.
>
> Having a great product that is a mess behind the scenes is fine for a
> start.  Uncle Bob makes this exact point in the book.  There was the
> best debugger in the industry, awesome product, everyone used it, but it
> fell behind because the code was a mess and it was getting harder and
> harder to extend over time.
>
> Yes we need a relevant product.  But if we want the product to stay
> relevant, then it needs to be as clean as possible under the covers.
>
> 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/20130919/078d49e7/attachment.html>