Rules of Thumb for Software Engineers

Based on my own experience, some of my favorite books and blog posts, and advice from friends, I’ve come up with this. What do you think? What should I add? Please comment!

Personal Effectiveness Rules of Thumb

  1. When you have your best idea ever, always remember that the idea is just 1% of the journey Yes, ideas are cheap. At least in the world of software engineering and product development, everyone and their grandfather have ideas that may be great. The distance between the idea and the reality is great. Here’s Steve Jobs about ideas

  2. When your project is late, never ADD people Most of the time this will slow you down. The reason is that with each additional person you add to a project you’ve created that many more paths of communication. If a project is late, adding people to it will make it later. See * The Mythical Man Month by Fred Brooks.

  3. When planning your time, always allocate at least 20% to learning more Software engineering, programming languages, libraries, platforms, hardware and software are constantly changing. It take a real sustained effort to keep yourself up to date. What was a good or best practice a year ago may no longer be right.

  4. When arguing about a design or a feature, always stop and go ask a user. Good products don’t come from debate around a table, they come from discussion with the actual users. Don’t guess, don’t argue, go ask! This is known as “getting out of the building”.

  5. When planning a project, always work in short increments. Follow Agile practices, whatever your favorite flavor is, scrum, XP, Kanban, it doesn’t matter. Different teams and people like different approaches. And they change and evolve all the time. But there are eternal truths there. Work in small chunks. Even smaller. Even smaller. Don’t change many things at once because when your code invariably breaks, you won’t be able to tell why.

  6. When you are spinning your wheels, always stop, think, and only then act. Google It! The amount of knowledge and down and dirty solutions that you can find on google is infinite. See a strange error message? Google it! And learn how to edit the error message, removing the parts that are specific to you so that you get matches. Or ask on the right forum or mailing list. You need to learn how to ask a question in a way that it will be answered. Make it as easy as possible on the answerer.

  7. When you are posting on a technical forum, always formulate the question carefully. Here are the best practices:

    • Explain precisely what you are trying to accomplish
    • Give a step by step explanation of what you’ve tried and the result.
    • Give code samples, links to github accounts, and so on. If the code samples are not brief, create a gist and put the link in the post.
    • Include listings of the relevant data, file names, console logs, and versions of various software you use.
  8. When you are writing a ‘business’ email, always follow best-practices

    • If you expect action, have a single person in the to:
    • Know the difference between reply and reply all. Usually don’t reply all
    • The first sentence should state what action you are looking for
    • Keep it short and sweet. Make it “skimmable”.
    • Know your audience and write appropriately.
    • Get to the point. Be polite.
  9. When you have to write up a design or a spec, always keep it to a few pages. Prefer writing short ‘stories’ over writing long ‘specifications. There is no requirements ‘phase’ to a project any more. Write many short stories and prioritize them relentlessly. If the story is more effort to write than the code, you should be writing the code!.

Programming Rules of Thumb

  1. When coding, never go beyond the immediate requirement. Write only the code you need to solve the problem RIGHT now. You might think that this class clearly will need all this methods even though no one is calling them yet. This almost never works out. Don’t spend time to set things up for what you’ll need in a month. You’re usually wrong.

  2. When coding, always wait to optimize until later. Optimizing too early is one of the cardinal sins of programming. You never know where the bottleneck will be, The thing you think will be slow, will be fast, and vice-versa. Actually you might end up ripping it out anyway!

  3. When your own code mystifies or surprises you never accept that. Dig deeper.

    • Catch yourself engaging in magical thinking. If it worked yesterday, and not today, then something changed. Similar story as “It worked on my machine, why doestn’t it work in production?” Both of these are a symptom of magical engineering thinking. It’s just a computer. If the behavior changed, then something cause that change in the behavior. Methodically go through each thing that might be different and, like a scientist (or Sherlock) figure out what it was.
    • Don’t be satisfied with blind luck Copying some code without knowing what is going on is not a good idea. Eventually it will come back to haunt you. Be really curious!. If a certain change fixed the problem, investigate until you understand how it fixed the problem.
    • Learn to Debug Debugging is a craft in itself. Approach it like a scientist. Don’t poke blindly at the code, or solve the problem just by thinking about it. Have hypotheses to test. Do experiments.
  4. When your program blows up always stop and read the error messages. Catch yourself jumpint to conclusions or seeing what’s not there. Fight the impulse that you know what must have failed. Often the right answer is right there in the error message. It might be buried in the middle of a lot of noisy trace output, but discipline yourself to actually read it.

  5. If you think you spot a code smell always come back and eradicate it Train yourself to recognize (and HATE) code smells. Like nails on a blackboard, badly designed code should make your stomach turn or your skin crawl.

    • <%= ir “Never, Ever” %> Cut and Paste code. DRY is a law. If you see any duplicated code it is almost always a bad thing. Look for it and kill it.
    • <%= ir “Learn how to Refactor” %> This is a fundamental coding skill. When you see non-dry code or other violations, refactor ruthlessly.
    • never leave dead code behind** Delete it.
    • always keep your files, methods and functions short** Depending on the language and the program, the right number may vary. But a method that has more than 20 lines is almost always a serious code smell. A guideline would be 10 lines.
  6. When programming always use a source control system. It’s your safety net. This is especially true when working with other programmers. Learn your SCS tool so you are never reluctant to use it.

  7. When designing software, always keep concerns as separate as possible. Design for loose coupling. Pay attention to the Single Responsibility principle. Whether it’s a single class or function, a subsystem or module, or a whole system, minimize dependencies. Learn about dependency injection and other techniques for decoupling.

  8. When doing object oriented programming always avoid using class inheritence While tempting, it is almost always better to avoid using inheritence in your class design. It brings undesireable coupling with little benefit that could be had in a simpler way.

  9. When programming always use ‘intention revealing names’ Chosing the right names for classes, variables, methods is one of the best ways to ‘document’ your code. Follow your language’s naming conventions closely and then create names that reveal your intention. Name things after what they do, not after how they work! Also make sure names are internally consistent. (Ref: Intention Revealing Names)

  10. When programming, always comment your code, but not too much. The exact line is a matter of (fervent) debate but it is almost universally accepted that having no comments is a bad idea and that its easy to have too many comments. Keep your comments at the start of each source file, and at the start of each method. Occasionally you might want to put a few lines of comments inline. But that desire often alerts you to a refactoring opportunity.

  11. When learning new things never fall in love with the shiny toys It’s ok to be proud in your expertise and trying to perfect your craft. But platforms and languages come and go, and you must remain alert to newer and better ways to solve problems as they are invented. Don’t fall in love with a language or platform. It will change and the specific details you memorized will eventually become useless.

Credits

Many of these are from books, blogs and my own experience. I will list all the credits that I can identify but I think in some cases these rules are so deeply embedded that I cannot recall where I got them from. If you see sonething that you think you came up with, I appologize!

Better to be a software developer than a college professor?

Other than the headline, which is amusing, I am not sure about the methodology or significance of this study in US News (do they still exist?). And it seems that many professions, e.g. College Professor, don’t even get mentioned. Is it because they don’t even make the top 100? I doubt it. Anyway, Here’s more about the US News and World Report’s assessments:

“All jobs aren’t created equal. In fact, some are simply better than the rest. U.S. News 100 Best Jobs of 2014 offer a mosaic of employment opportunity, good salary, manageable work-life balance and job security. Some careers offer just the right mix of these components – for instance, nearly 40 percent of our picks are health care jobs – but the list also includes strong showings from occupations in the social services and business sectors. And for the first time, our No. 1 pick is a technology job. Read more on how we rank the best jobs, and check out our complete list.” Read the whole article and see the report in US News and World Report.

 

Software Developer Meat Market

An interesting article in Forbes about Software Developers and Development in general, The Rise of Developeronomics. While here and there he is promoting old chestnuts which may or may not be true there is a core argument which is quite intriguing. It goes something like this:

  1. All companies are becoming software companies, meaning they are driven by software whatever their business actually is.
  2. Hence a key resource to a successful business is an effective, efficient and scalable capability to create innovative computer driven systems. Programmers are scarce.
  3. Hence the way to invest in the future is to cultivate great and excellent developers who believe in you, are willing to follow your vision and will commit to your projects.

Sometimes I wonder whether business writers come up with a two paragraph insight or story idea and bulk it up into a 3 page article, or whether I am just not appreciating their craft. In any event, Venkatesh Rao writes:

“Investing in good developers is such a good bet at the moment, that if you have money and you happen to find a talented developer who seems to like you and wants to work with you, you should give him/her your money to build something, anything, even if you have no really good product ideas (those are cheap; I’ll sell you a dozen for a dollar).” (from The Rise of Developeronomics)

Wow. And a little further on he warns:

“In what follows, I am deliberately going to talk about the developers like they are products in a meat market. For practical purposes, they are, since the vast majority of them haven’t found a way to use their own scarcity to their advantage. Which means others find a way to do so. In capitalism, every human is either a capitalist, somebody else’s capital, or economically worthless. Today, this abstract point specifically translates to: people who can invest in developers, developers, and everybody else. (from The Rise of Developeronomics)

Read the whole of The Rise of Developeronomics.

Is your software developer any good?

Are you thinking about hiring a software developer to build your system? Here are “8 Things You Ought to Know If You Do Not Know Anything About Hiring a Software Developer“. He says:

“I did not come to this industry with a software background. I studied math, physics, business, then finance. But over the past 12 years or so, I have learned quite a bit about how to pick a software… “friend”. So let me share with you 8 things I would want to know if I was starting afresh.” (from “8 Things You Ought to Know If You Do Not Know Anything About Hiring a Software Developer“)

Can I be your friend?

Customer vs. Consultant: Excellent advice

From an article called “Effective Customer Consultant Relationships”:

“As a customer, how can you get the most out of your consultants? As a consultant, how can you deliver what your customers really want? I have been on both sides of this relationship and experienced both successful and unsuccessful results. In this post, I will go through the typical aspects of these types of relationships and identify action items that I have used to forge effective and lasting customer consultant relationships for both parties.” (from “Effective Customer Consultant Relationships”)

If you are a tech consultant or are thinking of hiring one, this article has some excellent advice.

Designed As Designer

If you are interested in design and especially design and architecture of software, and you have a philosophical bent, you will enjoy this essay… I can’t even attempt to summarize it’s content, and even the abstract from the paper itself is quite inscrutable:

“Conceptual integrity arises not (simply) from one mind or from a small number of agreeing resonant minds, but from sometimes hidden co-authors and the thing designed itself.” (From Designed As Designer)

What can I tell you. The author is the Richard Gabriel, a luminary of the computer world. Here’s the article: Designed as Designer.

How do you feel about Software Patents?

I am not dead set against software patents, although I’ve been on both sides of the issue.

I am the proud inventor listed on 3 or 4 patents. Some are more worthy in my opinion that others. I was also leading a development team that had to stand on its head to avoid conflicting with a patent that everyone agreed should never have issued, but we didn’t have the nerve or resources to contest.

So I was interested to see some behind the veil of “Intellectual Ventures”, Nathan Myhrvold’s IP/Patent company:

“…But IV is not buying inventions. It’s buying patents. And most software engineers will tell you, at least when it comes to software, a patent and an invention are not the same. Lots of patents cover things that people who write software for a living wouldn’t consider inventions at all… (from When Patents Attack)

Is Software Eating the World

Marc Andreeson has a really good, optimistic article in the Wall Street Journal about the future foundational role of Software in all industries of the world’s economy:

“[…snip]Finally, the new companies need to prove their worth. They need to build strong cultures, delight their customers, establish their own competitive advantages and, yes, justify their rising valuations. No one should expect building a new high-growth, software-powered company in an established industry to be easy. It’s brutally difficult.

I’m privileged to work with some of the best of the new breed of software companies, and I can tell you they’re really good at what they do. If they perform to my and others’ expectations, they are going to be highly valuable cornerstone companies in the global economy, eating markets far larger than the technology industry has historically been able to pursue.

Instead of constantly questioning their valuations, let’s seek to understand how the new generation of technology companies are doing what they do, what the broader consequences are for businesses and the economy and what we can collectively do to expand the number of innovative new software companies created in the U.S. and around the world.

That’s the big opportunity. I know where I’m putting my money. […end snip]” (from Wall Street Journal)

A fine article. One thing that does go through my mind is that even though he cites opportunity after opportunity in the full article, my observation is that it is quite hard nowadays to get people to pay for software in any form. We’ve gotten used to free, even in the enterprise. Yes some do succeed, big, but many many do not make it.

You must have a deep, illogical, passionate belief in your company and then you have to actually be really really good at execution.

A great article about scientific discourse

This article is called “Fact and Folklore In Software Engineering” and while it is about that, the part that was more interesting to me was the first section talking about Scientific Discourse:

“This article is about why some “facts” refuse to die, and about how to avoid being fooled by opinion disguised as scientific “fact”. We start, therefore, with some observations on science and facts.” (from “Fact and Folklore In Software Engineering”)

Here he goes on to describe “The messy workings of scientific discourse”. It’s clarifying explanation of a process that we understand intuitively but actually has a rigorous process:

“Bruno Latour is one of the keenest observers I know of the work that scientists really do, and one of the most punctilious in clearing away the myths and misconceptions about how science is in fact done. I have found good use in some of the tools he created to assess the status of an ongoingdebate about a matter that falls within the purview of science, one that hasn’t been settled – what he calls a controversy.” (from “Fact and Folklore In Software Engineering”)

After lots of further interesting detail about this idea, he finally comes back to the question: “So what is known about programmer productivity?”:

“We can now circle back to this widely circulated “fact” of the software profession, according to which “programmer productivity varies by a factor of 10 (or 5, or 20) between the best and worst individuals”. This is a remarkable statement, not least because of its implications: for instance, programmer compensation does not vary accordingly.” (from “Fact and Folklore In Software Engineering”)

After this introduction he goes on to thoroughly take apart this concept as nothing more than unsubstantiated, oft-repeated folklore, based in some really old, actually inapplicable, and incorrectly cited studies.

But they stick because there is a grain of truth in them. The problem is that it’s just a grain of truth. It’s a wonderful article. Read “Fact and Folklore In Software.