Developer Philosophy

Kernighan's Law - Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.

A great rule of thumb I found useful while learning under great tutorship (way back when) was, look at your check-in, (svn at the time) if you think you will remember it in 5 months in less than 15 mins then it’s okay.. But still have someone put eyes on it before clicking. SVN made us careful maybe..

I'd be a bit wary of taking 'simplicity' as a goal. Some people read that and think to write shorter, cleverer code instead of longer, more straightforward code which might have a few redundancies. (E.g., people often praise FP languages and Lisp-like languages for their very flexible control flow, but adding custom abstractions can result in shorter code that is difficult for newcomers to understand.)

On the other hand, too much modularity and factored-out code can also obscure the behavior of a program, even if each module has a well-defined role and satisfies its interface. (E.g., big Java programs can have hundreds of classes with small method bodies and lots of calls to other classes and interfaces. If you see an interface call, but the object came from somewhere several classes away, then good luck figuring out which implementation gets called.)

I'd say that the ultimate moral is "Keep the flow of logic and data relatively linear (or at least, no more complex than it needs to be to solve the problem). Avoid dicing it up between a dozen different spots, or performing crazy stunts with it, so that only an expert can understand what's going on. And just because some logical constructs (like dynamic dispatch) are unwritten doesn't mean they don't create mental load."

Someone below already commented [0]

> I think any attempt to distil hard earned experience and domain awareness will eventually devolve into misplaced generalisms.

Ground up rewrites are a gamble. Classic Spolksy essay [1] about Netscape losing their lead to Internet Explorer is a must read.

Briefly:

1. You think you know how to build the new version, but you really don't. Years of improvements of the old version, years of bug fixes, years of business knowledge are below the surface.

2. The new version is going to have new bugs.

3. While you're rebuilding everything from scratch your competition is improving their product.

0: https://news.ycombinator.com/item?id=42921426

1: https://www.joelonsoftware.com/2000/04/06/things-you-should-...

generalisms are fine as long as you don't try to turn it into a hard and fast rule.

generalisms contain knowledge that generally applies, but i think it's well understood that there will always be times where it doesn't apply.

The author has a few words about Clean Code https://qntm.org/clean

A better recommendation is "A Philosophy of Software Design" by Osterhaut.

Well, there's a gauntlet being thrown down if I ever saw one.

For me? Maybe something like:

1. All rules have exceptions - have places that should be exceptions. Rigidly enforcing a rule may be better than having no rule, but thoughtfully following the rule (almost all the time) is even better. Know your rules, know why they're the rules, and know when it might be reasonable to make an exception. (Maybe this says that "rules" are really more like "guidelines".)

Rules often come in opposite pairs. I think of it like this: In Zion National Park, there's a hike called "Angel's Landing". You wind up going up this ridge. On one side is a 1000-foot drop-off. On the other side is a 500 foot drop-off. The ridge isn't all that wide, either. If you look at one cliff, and you think "I need to be careful not to fall off of that cliff", and you back too far away from it, then you fall off of the other cliff.

I think software engineering can be like that. There is more than one mistake that you could make. Don't be so busy avoiding one mistake that you make the opposite mistake. This takes thoughtful understanding, not just blindly following rules.

2. In general, don't repeat yourself. Early in my career, a coworker and I learned to ask ourselves, "Did you fix it everyplace?" It's even better if there's only one place.

But... It is common that things start out the same, and then become slightly different (and it gets covered with an "if"), and then become more different (and now we have several "if"s), and then become even more different. Eventually it can become better to decide that these are actually different things, and split them. Knowing when to do so is an art rather than a science, but it's important.

3. The most general problem cannot be solved. The trick is to do something simple enough that you can actually finish it, but hard enough that it's actually worth doing. You cannot address this just by changing the lines of code you write; the problem is at the specification level (though it can affect the specification of a module or a function, not just a project).

4. Code that is "close to perfect", delivered now, may well be better than code that is absolutely perfect, an uncertain amount of time in the future. It depends on how many imperfections there are, how likely they are to be hit, and how damaging they are when they are hit. Code that is close to perfect may be perfectly usable to many people; code that hasn't shipped yet is currently usable to nobody. (Note well: This is not an excuse for sloppiness! It is an excuse for not going completely hog-wild on perfectionism.)

5. You've got a perfect design? Great. As part of delivering the design, deliver an explanation/roadmap/tour guide for it. (If it were an electrical design, it might be called a "theory of operation".) Consider checking it in to the version control system, right beside the code - like, in the top level directory.

6. All these things take maintenance. You have to revisit your "don't repeat yourself" decisions. You have to revisit what is within scope and out of scope. You have to revisit which bugs are tolerable and which are not. You have to update your design documents. Take the time and do the work. If you don't, your program will slowly become more and more brittle.

Back in the 1970s, when I was just a high school kid reading computer magazines, I saw references to a study (I believe by IBM), that said in production code, that 70 or 80% of the lines of code was error handling; only 20% or 30% was the "golden path". I'm not sure I saw an actual reference, even then, and I certainly cannot give a reference now.

Does anybody know the study in question? (I have never seen another study on the topic. Does anyone else know of one?)

This was almost certainly either done in assembly or PL/I or Algol or something. Do more modern languages change it? Exceptions? Dual-track programming (options or Maybes)?

Regardless of exact numbers, yes, error cases are something you have to think about all the time.