My favorite principle for code quality

Good design is not about the code. Good design is about the people who are going to work with that code. Understand your audience. Get to know what they like and what they don't like. Write your code in a way that will delight your audience. Give them what they expect to see.

Of course, this is exceptionally shallow advice because no programmer can actually be so selfless. If you write code that pleases your audience you will usually have to do so at the expense of yourself. It is not possible to write good code that you dislike -- at least not long term.

So the trick to good design is always putting a bit of yourself in the code and always putting a bit of your colleagues in the code. It's striking that balance where you are satisfied, but also where they are satisfied. This requires working in small increments, and sharing what you are doing. It requires watching what your colleagues are doing and looking for opportunities to borrow. It requires questioning, evaluating, praising, explaining and coaching.

And if you are working by yourself: do whatever the hell you want. Why are you so worried about what other people think? If you are trying to improve what you are doing, don't do so by reading about the opinions of others. Read code, not blog posts. Write code, not design diagrams. Work slowly, try out ideas you've seen in other code and evaluate their success. When you get the chance, work with others to broaden your horizons.

Please, please, please absolutely disregard this advice. More errors, pain and suffering come from early abstraction and poor understanding then not enough abstraction.

Build simple, extend as needed. It's a 'frggin stats page where a developer forgot to remove a call. It could of been written much cleaner initially, but breaking it into a bunch of classes at the initial stage is fruitless abstraction.

It's always the same pattern and it's like the programmer's version of the one weird trick. Show ten lines of (contrived) code and talk about its potential to be flawed, and then 'fix' it by explaining 50+ lines of code that has to be abbreviated or split into pieces to keep the article flowing. What quality actually means in this context is unclear, but it feels like tidying your bedroom as a child: hide the clutter in various places to give the appearance of cleanliness, while actually creating more of a mess for the next cleanup in the process.

And like many programming maxims, advising to abstract early is just as bad as advising to not abstract at all. Better abstraction will become more apparent as you see how your system fits together and how parts of it can be lifted up to a higher level, and this kind of intuition will only come with patience and experience.

  // global, since the cached values were apparently global in the original
  let cache = {};
  let lastCachedTime = 0;

  // Utility for fetching potentially cached values, or computing them 
  // if there's no valid cache entry.
  let cached = (id, recompute) => {
    // I don't love this policy, but thankfully it's all in one place.  
    if (lastCachedTime <= lastMidnight() || lastCachedTime <= lastNoon() {
      cache = {};
      lastCachedTime = Time.now();
    }
    if (!(id in cache)) {
      cache[id] = recompute();
    }
    return cache[id];
  };

  // now we get to have a nicely factored, simple, conceptually independent, 
  // declarative code for the dashboard.
  function displayDashboard() {
    print("Total Users: " + cached("numContent", => countUsers());
    print("Articles written: " + cached("numArticles", => countArticles());
    print("Words written: " + cached("numWords", => countWords());
  }

I prefer this lambda-based design because it reifies the "form" into a single, callable, function: cached(). If you want to use the idea of cached(), you don't have to subclass anything or know about its implementation details— just call it.

(PS. the code's even nicer in CoffeeScript)

I'm all for good software design, but claiming a design process can eliminate bugs is more fantasy than reality. Bugs typically come from unforeseen requirements or application states.

Yes, planning reduces bugs, but bugs are still inevitable no matter what software design process we use.

The fixed code still has a bug. It assumes successive calls to lastMidnight() within the method will always return the same date. But presumably, if partway through the method it ticks over to midnight, that would not be the case. So some stats would be updated during one call, and the rest would be updated during the next call.

That would violate this requirement:

> They had previously decided all stats should refresh simultaneously;

"Bad programmers worry about the code. Good programmers worry about data structures and their relationships."

The author refactors some code to revolve around a "DashboardStat" and explains it came from "thinking about how the code is derived from the design." Personally, I think it came from putting the data & its structure first.

First, there was a bit of bashing of design patterns and refactorings and says we can forget all that in order to make it sound like he was going to drop some magic fundamental wisdom. Which he then says is "Embedded Design Principle".

Then he proceeds to describe an evolution of a piece of software into a bit of a mess, then proceeds to solve it by "AND here is a design that solves it". No method or process for getting to that design, just "here it is!" .... drop the mic, exit stage left. So basically his advice is dont write crappy code, some how magic up a design that might or might not be robust for the future that reveals your design.

Looking at some of his other stuff, he uses a similar "strawman" ish approach to first highlight some technique like (TDD), come up with some crappy code, and use it as some kind of justification for what he thinks.

Funny thing is, the stuff he trivialized actually are exact micro techniques that allow one to create code thats shows its design.

However, for this article, there is a simpler idea that is useful when tackling code like this ( I first came across it in martin fowlers UML Distilled ) and that was the idea of "Levels of Perspective". Which there is Conceptual, Specification, and Implmentation. Since his code seems to have purposely mushed all those things together, its an easy way to look at this code and make it better. I won't go into the exact details, but given a piece of crappy code either in the beginning stages or even the end stage and start decomposing it, first seperating specification and implementation, then as one gains insight, seperating things into composable conceptual ideas. To achieve this, you want to use things like TDD, Refactoring, Patterns, but, and the real trick, only as is demanded to shape the code into a simple design that is modular and composable.

Personally I keep coming across code where the "design" as indicated by names and comments indicate one thing.... but the fact of the code indicates another design.

Now if this indicates a bug, ie. Incorrect behaviour, yup, fix it.

But usually it has been "tested into the shape of a product". ie. The names and the comments and the data structures indicated first, draft, incorrekt, thoughts... and the reality of the code _is_ the correct behavior.

Usually at that point I refactor to reveal what the design really is, down at the mathematics of the code, not what the designer thought it was.

This principle still works with the author's example. Most of the refactoring he did boiled down to modeling the data more accurately.

Pretty sure that's attributed to Plato. Well I guess he called them είδε but he couldn't wait around for English to get invented.

Additionally, the authors "better" design now abstracts the primary performance problem out of sight of the developer. The main problem I see is that they are making multiple passes through the data to extract different metrics. By abstracting early they miss the opportunity to improve the performance by calculating all the metrics in one pass. The new design has hidden the root cause of the problem and prevented a developer from fixing the core problem without chucking out the entire design.

It wastes a lot of time when I try to abstract early. You can't solve a problem without all the variables.

Peter Principle + Embedded Design Principle = Conway's Law