5 ms·

How I Develop Things and Why

202 points by jorde 15y ago

conroy 15y ago
I've started following this rule for all of my personal projects. However, many of us find it difficult to apply this rule to the software we write on the job. Most of the projects we work on aren't for us. They are for customers with vastly different needs. When you are creating that type of product, I don't think this rule really applies.
- cluda01 15y ago
  Writing use cases and thinking about how the user is going to interact with your system is a very large part of creating correct and defect free software. Besides the obvious "will the user get it" it has a huge benefit when it comes time to design of your test suite. Consider an imperative programming language where you can have null values. A null value most often means that some piece of data is optional or not required for operation. One example of this could be a form field for users to enter their real names. If you're making a social site ala reddit or something else you might want to make real names optional. Hence when someone fetches the real name field or passes it as an argument to another method it could be null. Designing the use cases will help you because when it comes time to write the implementation and test cases you have a concrete understanding of why the value is null. If your program is sufficiently complex this real name field may end up being passed around to several seemingly unrelated modules. Having the use cases drawn up prior to implementation will help you quickly diagnose those crashes or null pointer exceptions and more generally answering the question "Why is this value null?" Edit: Ineligibility ++
  - ThaddeusQuay2 15y ago
    Or obviate all of the potential downfalls with null by simply sticking "anonymous" in the name field.
daenz 15y ago
> Before I start writing a single line of code, I write the README and fill it with usage examples. I pretend that the module I want to build is already written and available, and I write some code with it. I write the same way. It forces you to think of how intuitive and natural your code should be. I've run into so much code that makes me wonder, "did they even consider how someone will want to use this?" Software should resonate with how people expect to use it, coming in with little-to-no understanding of the actual implementation.
- agentultra 15y ago
  I write the tests first which is kind of the same thing except that I can actually execute that API and see if what I wrote actually works. Writing good tests first also helps me constrain my implementations to be as simple as possible as well. Otherwise my tests get hard to write and that's a sign things are probably going in the wrong direction. Often though you can't have your cake and eat it too. There are two schools of thought: worse is better and the right way. The former way eschews simple APIs for simple implementations. The latter is pretty much the opposite. I'm currently working on a project where I'm trying to maintain a simple API across three different, related services. One of those services has such a simplistic interface that maintaining the simple API that the other two have has made the implementation comparatively complex. Now I have to take extra care to make it as simple as I can... but it's still complicated. Which means my poor future developer who has to maintain this thing will need lots of documentation in order to understand it (fortunately I maintain TODO lists and notes as I go to accompany my stories... forming a sort of journal of my development process for each project; it makes it easy to pull out useable "how and why" documentation).
  - quanticle 15y ago
    The problem is that the worse is better school usually wins over the long run. Jamie Zawinski has a great essay on this [1]. Unix was a "worse is better" MULTICS. DOS was a "worse is better" CP/M. Windows was a "worse is better" MacOS. The advantage of simple implementations is that you can get them in front of users right now, and then iterate your implementation until you have something that's cheap and adequate. Not perfect. Not even great. But adequate. However, as the essay points out, cheap and adequate today beats pricey and perfect tomorrow every time. [1]: http://www.jwz.org/doc/worse-is-better.html http://www.jwz.org/doc/worse-is-better.html
AznHisoka 15y ago
I'm not sure if this principle is a good one for starting a business. Many of us aren't exposed to meaningful problems outside of coding, using the internet, etc.
- bitops 15y ago
  > Many of us aren't exposed to meaningful problems outside of coding, using the internet, etc. Are you certain? Unless you live at home 24/7, you're interacting with the world every day. If you're like me, you regularly run into situations that are "sub-optimal" in terms of how much hassle you have to deal with to get things done. I think the key is to stop thinking that meaning problems only exist in the realm of computers. In fact, most of the meaningful problems in our world are outside of the realm of software precisely because no-one has looked at the problem and thought "hey, software could make this easier". An example we're all painfully aware of: medical records. There's a TON of paper involved, little co-ordination between doctors, the list goes on. People are working on the problem, but the revolution hasn't arrived yet. A different way of putting it comes from Paul Graham: "don't think that you're trying to start a startup, instead think that you're trying to solve a problem".
  - AznHisoka 15y ago
    Well, ok, let's talk about medical records. Not many people have the expertise/knowledge to tackle that issue (they can acquire it). They're not around doctors, and healthcare to experience the pain point and understanding the nuances of tackling that problem. On the other hand, based on our daily interactions, we're more predisposed to making a better Javascript framework, developer tools, better ways of managing our social contacts, etc.
randomtyler 15y ago
This is basically customer testing, except treating yourself like the customer. This can be a good starting point, but is also dangerous for a multitude of reasons you already know and I won't reiterate. It's a good way to get started thinking about your solution, but does not replace talking to real customers whose problems you're trying to solve.
zoltarSpeaks 15y ago
It's always great to be reminded to step away and remember why we do what we do, it can easily be lost in the complexity of problem solving. Nice article.
reuser 15y ago
There are lots of ways of doing things, and more than a few of them are sensible. Without zeroing in on a specific well-defined problem, you usually won't have any hope of identifying anything like 'optimal' solutions - let alone uniquely optimal solutions. "user in mind" and "have a real problem" and "get things done" and "responsive design" and "designed for Humans" and "make it happen" and "never compromise the API" are vague platitudes which don't even provide interpretable advice, let alone specific usable information. It can be slightly obnoxious when a battle-hardened grayhair begins to hold forth on vague general principles in this way - it can still be productive to listen insofar as knowledge is being shared. What information is being shared here, and what experience or reasoning is there to ground it as knowledge?
gavanwoolery 15y ago
Nailed it. I've been very guilty of writing applications and APIs strictly oriented towards my own understanding. Also, I like how you throw a jab at all the BS metrics companies use to try and come up with a useless startup they can flip. ;)
adeelk 15y ago
I didn't understand the responsive design analogy. I assume it's not the operating system that the developer responds to, so what is it?
- kenneth_reitz 15y ago
  The problem.
  - adeelk 15y ago
    I don’t think the analogy from web design carries over, then, does it? You’re not using the word "responsive" with the same connotation.
known 15y ago
Sell first. Build later.
- jackcviers 15y ago
  ^^^^^^^ This. It is so important to be a great idea salesperson. Even if you are writing a OSS tool, if you want contributors you need to sell the idea.

202 points by jorde 15y ago

I've started following this rule for all of my personal projects. However, many of us find it difficult to apply this rule to the software we write on the job. Most of the projects we work on aren't for us. They are for customers with vastly different needs. When you are creating that type of product, I don't think this rule really applies.

cluda01 15y ago
Writing use cases and thinking about how the user is going to interact with your system is a very large part of creating correct and defect free software. Besides the obvious "will the user get it" it has a huge benefit when it comes time to design of your test suite. Consider an imperative programming language where you can have null values. A null value most often means that some piece of data is optional or not required for operation. One example of this could be a form field for users to enter their real names. If you're making a social site ala reddit or something else you might want to make real names optional. Hence when someone fetches the real name field or passes it as an argument to another method it could be null. Designing the use cases will help you because when it comes time to write the implementation and test cases you have a concrete understanding of why the value is null. If your program is sufficiently complex this real name field may end up being passed around to several seemingly unrelated modules. Having the use cases drawn up prior to implementation will help you quickly diagnose those crashes or null pointer exceptions and more generally answering the question "Why is this value null?" Edit: Ineligibility ++
- ThaddeusQuay2 15y ago
  Or obviate all of the potential downfalls with null by simply sticking "anonymous" in the name field.

daenz 15y ago

> Before I start writing a single line of code, I write the README and fill it with usage examples. I pretend that the module I want to build is already written and available, and I write some code with it. I write the same way. It forces you to think of how intuitive and natural your code should be. I've run into so much code that makes me wonder, "did they even consider how someone will want to use this?" Software should resonate with how people expect to use it, coming in with little-to-no understanding of the actual implementation.

agentultra 15y ago
I write the tests first which is kind of the same thing except that I can actually execute that API and see if what I wrote actually works. Writing good tests first also helps me constrain my implementations to be as simple as possible as well. Otherwise my tests get hard to write and that's a sign things are probably going in the wrong direction. Often though you can't have your cake and eat it too. There are two schools of thought: worse is better and the right way. The former way eschews simple APIs for simple implementations. The latter is pretty much the opposite. I'm currently working on a project where I'm trying to maintain a simple API across three different, related services. One of those services has such a simplistic interface that maintaining the simple API that the other two have has made the implementation comparatively complex. Now I have to take extra care to make it as simple as I can... but it's still complicated. Which means my poor future developer who has to maintain this thing will need lots of documentation in order to understand it (fortunately I maintain TODO lists and notes as I go to accompany my stories... forming a sort of journal of my development process for each project; it makes it easy to pull out useable "how and why" documentation).
- quanticle 15y ago
  The problem is that the worse is better school usually wins over the long run. Jamie Zawinski has a great essay on this [1]. Unix was a "worse is better" MULTICS. DOS was a "worse is better" CP/M. Windows was a "worse is better" MacOS. The advantage of simple implementations is that you can get them in front of users right now, and then iterate your implementation until you have something that's cheap and adequate. Not perfect. Not even great. But adequate. However, as the essay points out, cheap and adequate today beats pricey and perfect tomorrow every time. [1]: http://www.jwz.org/doc/worse-is-better.html http://www.jwz.org/doc/worse-is-better.html

AznHisoka 15y ago

I'm not sure if this principle is a good one for starting a business. Many of us aren't exposed to meaningful problems outside of coding, using the internet, etc.

bitops 15y ago
> Many of us aren't exposed to meaningful problems outside of coding, using the internet, etc. Are you certain? Unless you live at home 24/7, you're interacting with the world every day. If you're like me, you regularly run into situations that are "sub-optimal" in terms of how much hassle you have to deal with to get things done. I think the key is to stop thinking that meaning problems only exist in the realm of computers. In fact, most of the meaningful problems in our world are outside of the realm of software precisely because no-one has looked at the problem and thought "hey, software could make this easier". An example we're all painfully aware of: medical records. There's a TON of paper involved, little co-ordination between doctors, the list goes on. People are working on the problem, but the revolution hasn't arrived yet. A different way of putting it comes from Paul Graham: "don't think that you're trying to start a startup, instead think that you're trying to solve a problem".
- AznHisoka 15y ago
  Well, ok, let's talk about medical records. Not many people have the expertise/knowledge to tackle that issue (they can acquire it). They're not around doctors, and healthcare to experience the pain point and understanding the nuances of tackling that problem. On the other hand, based on our daily interactions, we're more predisposed to making a better Javascript framework, developer tools, better ways of managing our social contacts, etc.

randomtyler 15y ago

This is basically customer testing, except treating yourself like the customer. This can be a good starting point, but is also dangerous for a multitude of reasons you already know and I won't reiterate. It's a good way to get started thinking about your solution, but does not replace talking to real customers whose problems you're trying to solve.

zoltarSpeaks 15y ago

It's always great to be reminded to step away and remember why we do what we do, it can easily be lost in the complexity of problem solving. Nice article.

reuser 15y ago

There are lots of ways of doing things, and more than a few of them are sensible. Without zeroing in on a specific well-defined problem, you usually won't have any hope of identifying anything like 'optimal' solutions - let alone uniquely optimal solutions. "user in mind" and "have a real problem" and "get things done" and "responsive design" and "designed for Humans" and "make it happen" and "never compromise the API" are vague platitudes which don't even provide interpretable advice, let alone specific usable information. It can be slightly obnoxious when a battle-hardened grayhair begins to hold forth on vague general principles in this way - it can still be productive to listen insofar as knowledge is being shared. What information is being shared here, and what experience or reasoning is there to ground it as knowledge?

gavanwoolery 15y ago

Nailed it. I've been very guilty of writing applications and APIs strictly oriented towards my own understanding. Also, I like how you throw a jab at all the BS metrics companies use to try and come up with a useless startup they can flip. ;)

adeelk 15y ago

I didn't understand the responsive design analogy. I assume it's not the operating system that the developer responds to, so what is it?

kenneth_reitz 15y ago
The problem.
- adeelk 15y ago
  I don’t think the analogy from web design carries over, then, does it? You’re not using the word "responsive" with the same connotation.

known 15y ago

Sell first. Build later.

jackcviers 15y ago
^^^^^^^ This. It is so important to be a great idea salesperson. Even if you are writing a OSS tool, if you want contributors you need to sell the idea.