My Rules of Software Engineering

articles
,

Over the years, I've compiled some rules about software engineering. The list is incomplete, contradictory, and I reserve the right to add or delete rules as I remember them.

  • Rule #1: The customer might not always be right. In any well-designed software product, if the customer comes to you with a problem that your software should already handle correctly, 99.9% of the time, the customer is doing something wrong. It is in your and your customers' best interests to treat the customer's narrative with suspicion, because what they're actually trying to tell you is that you either have a bizarre edge case or you have an opportunity to improve your user experience. In my career, I've heard customers state with no ambiguity that the software won't print something, but then find that a different printer than they intended has dozens of copies of the thing they printed sitting in its output tray. The customer would be wrong in this case, but the real problem is that the user experience doesn't make it apparent they're printing to a different printer than they intended, and this should be pointed out to them in the UI.
  • Rule #2: Fred Brooks is always right. Fred Brooks wrote The Mythical Man-Month and did software engineering before your parents were born. It doesn't matter that terminology has changed (agile, scrum, Kanban, whatever) - it's largely just rehashing of the same techniques that Mr. Brooks implored everyone to use in 1975. In 2016, people in charge of development teams, which nowadays might not have any experience with engineering at all, and might have multiple seemingly incompatible roles within an organization, still make the same mistakes that Fred Brooks wrote about in The Mythical Man-Month. If you're ever in a situation where someone wants to schedule two developers to get a feature done twice as fast, pump the brakes and refer to this rule. If you're estimating how long something will take, take your best guess and multiply it by 9 (see page 5 of The Mythical Man Month). Engineers never include testing, debugging, planning, or documentation in estimates.
  • Rule #3: Leave code better than you found it. Your code sucks. My code sucks. Any time you check new or modified code in, it should at the bare minimum not be worse than the code you're not changing. Ideally, it's better. See something yucky? Pick up the trash!
  • Rule #4: If it sounds too good to be true, it is. This is general advice. If something was way easier than you thought it was going to be, you've forgotten something important, or haven't encountered a major problem that you will.
  • Rule #5: Use good tools. PHP is not a good tool. Classic ASP is not a good tool. ASP.NET WebForms is not a good tool. ColdFusion is not a good tool. Yes, I know lots of people use those tools, and I know that lots of successful websites and businesses use those tools, but they all have some major shortcomings that make them hard to replace, which creates a culture of shitty code. You don't want to create a culture of shitty code. If it's hard to write tests because the programming language or framework doesn't have an easy way to write tests, you're not going to write good tests, or you're going to leave the stubs in place.
  • Rule #6: Sometimes good tools have huge holes you have to overlook. Ember.js is awesome, and Ember CLI was a huge improvement to developing Ember applications. Unit testing was basically impossible before Ember CLI (you could do it; almost nobody did), and after Ember CLI it was automatic and easy. Except that there was perhaps too much isolation, and components couldn't be integration tested for many versions. Now, it's possible, and I have a ton of stub tests because I couldn't write effective integration tests for my components. And I still can't, because I'm stuck behind some major changes. This is not unlike the Angular.js changes that have come up, except that Angular.js outright broke all compatibility between the new version and the old version.
  • Rule #7: There is no "someday". I will probably never fix those tests. Neither will you. You'll never get time to fix all of the bad designs and missing tests, so you have to just do it alongside something else.

There are more rules, I just can't think of any, and I need to go review a pull request. I'll probably return and update this beast.