5 ms·

As always the problem is the specification. Once you sit down and write the formal specification, suddenly the implementation becomes much clearer.

by xfer 6y ago

jjav 6y ago
I wish this was a more widely held understanding. Document first, code later. Makes nearly all problems easy. Jumping to writing code first is a future disaster in the making.
- lmm 6y ago
  I find this is nonsense. Code is the best documentation; I've watched people spend hours debating a spec that becomes obviously broken as soon as you spend 5 minutes writing it up in something with a typechecker. Write the specification as code - make sure it's something that can actually be checked. Then you'll know whether it's actually any good.
  - blub 6y ago
    Documentation is written in a human language, can include other media like graphics and is addressed to humans. We write documentation for the same reason that we don't produce maps at a 1:1 scale: documentation offers a higher-level description that can be grasped without having to understand all the code. Not only is code not the best documentation, it's not documentation at all, outside of special cases where the entire code describes e.g. an algorithm and is encapsulated into one function.
    - mrbald 6y ago
      Code should have a hierarchical structure, so one could read it on the high level of abstraction and also zoom in gradually, as necessary — this is what they usually mean by “code is the documentation”, plan the reading process as you plan the functionality. It is a very important aspect of the readability, otherwise you will just sink in details when reading. But it is not easy to formally validate with tools, so naturally it is better to have both code and a picture and have discipline to keep them in sync.
      - deleted 6y ago
        [deleted]
      - Jtsummers 6y ago
        > Code should have a hierarchical structure, so one could read it on the high level of abstraction and also zoom in gradually, as necessary I agree with this. Some of the best code I've read and written was done in this style. Properly separating out components into a hierarchy of modules. > this is what they usually mean by "code is the documentation" I disagree with this. I don't think this is what people mean at all, because I don't think that most people do the first part. If they did, there wouldn't be so many problems with "code is the documentation". But most code is not written in a clear hierarchical fashion. Logic is weirdly commingled, and depending on the language you have an assortment of low-level bookkeeping mixed with high-level logic. I think they literally just mean "code is the documentation". One of the best/worst programmers I ever worked with is a perfect example of this. He'd always insist on the "code is the documentation", and his code always worked. But his code was absolutely awful to read for anyone but him. By way of analogy, I don't have a file system for physical papers. I have a literal chronological (by access time) stack. No one but me can make use of it, but it's very effective for me because I have a really good memory (though not as good as it was 20 years ago, I don't actually do this anymore because I have to work with others). That's his code. No one else can go into it and actually understand it (at least not easily), but he can jump in and make exactly the necessary changes. The code is not the documentation until it's properly organized, and maybe not even then.
  - gwd 6y ago
    > I find this is nonsense. Code is the best documentation Strangely, I find both gp and your claims to be nonsense. :-) I've definitely experienced what you've experienced -- until you actually have code, you don't know what works and what doesn't work. But it's frequently not at all obvious what code does, even in the normal case; and even code which looks obviously correct often has hidden complexities that you wouldn't have thought of. I find trying to explain in a comment why the code I've written is correct is pretty good in wheedling out all the ways in which it's not actually correct. So when things are really complicated, you need both: You need to have code that actually works, and you need to have text that attempts to prove that the code actually works.
    - brabel 6y ago
      > I find trying to explain in a comment why the code I've written is correct is pretty good in wheedling out all the ways in which it's not actually correct. I found that well written, expressive tests accomplish that really well. I use Spock[1] to write complex tests and I just can't recommend it enough if you're working with the JVM (Java, Kotlin, Groovy, Scala, Clojure). We have several thousands of Spock tests and it's amazing how they have scaled with us... they've grown to support extremely complex workflows that have nearly zero accidental complexity and are easily readable even if you have no experience with it. [1] http://spockframework.org http://spockframework.org
      - fulafel 6y ago
        With Clojure, are you writing tests in the Spock DSL (or is that Groovy?) or are you writing the tests in Clojure and importing Spock as a library and extending its classes etc?
        brabel 6y ago
        Spock tests must be written in Groovy, but they can call helpers from any JVM language, so we normally have lots of test helpers (traits) which we use to write tests with one-liners per action/assertion. If you write your app in any JVM language, you can use Spock to t test it because Groovy really has excellent interop with Java, hence JVM languages in general.
  - mrbald 6y ago
    "make sure it's something that can actually be checked" -- I'd love to find out about a sane (not purely academic, financially viable) way to do it. Since university days I know that a piece of paper is an irreplaceable tool - cheap and universal. I usually just draw it on paper, then code, then fix the code, then update the painting, and do it over again until both match each other and work. Never fails me.
- qz2 6y ago
  That's the key difference between forward engineering and hacking shit together. There is nothing wrong with prototypes but some people mistake them as production ready items because it looks like a whole load of work has been done.
- mtzet 6y ago
  I disagree in the general. It's very easy to write a spec that contradicts itself and is impossible to actually implement. Some things do have to be designed, and not just thrown together though. That may be through spec, but it could also be working things through on paper. Concurrency is certainly one of these. Other things need to be iterated on in code. I'd hate to play a platformer where the movement mechanics were specced out by a comitee before any code was made.
MaxBarraclough 6y ago
> formal specification Do you mean a written spec, or a proper formal specification? https://en.wikipedia.org/wiki/Formal_specification https://en.wikipedia.org/wiki/Formal_specification
- xfer 6y ago
  For concurrency related specs i was alluding to spin/TLA+.
  - MaxBarraclough 6y ago
    Great, thanks for clarifying.

As always the problem is the specification. Once you sit down and write the formal specification, suddenly the implementation becomes much clearer.

by xfer 6y ago

As always the problem is the specification. Once you sit down and write the formal specification, suddenly the implementation becomes much clearer.

jjav 6y ago

I wish this was a more widely held understanding. Document first, code later. Makes nearly all problems easy. Jumping to writing code first is a future disaster in the making.

lmm 6y ago
I find this is nonsense. Code is the best documentation; I've watched people spend hours debating a spec that becomes obviously broken as soon as you spend 5 minutes writing it up in something with a typechecker. Write the specification as code - make sure it's something that can actually be checked. Then you'll know whether it's actually any good.
- blub 6y ago
  Documentation is written in a human language, can include other media like graphics and is addressed to humans. We write documentation for the same reason that we don't produce maps at a 1:1 scale: documentation offers a higher-level description that can be grasped without having to understand all the code. Not only is code not the best documentation, it's not documentation at all, outside of special cases where the entire code describes e.g. an algorithm and is encapsulated into one function.
  - mrbald 6y ago
    Code should have a hierarchical structure, so one could read it on the high level of abstraction and also zoom in gradually, as necessary — this is what they usually mean by “code is the documentation”, plan the reading process as you plan the functionality. It is a very important aspect of the readability, otherwise you will just sink in details when reading. But it is not easy to formally validate with tools, so naturally it is better to have both code and a picture and have discipline to keep them in sync.
    - deleted 6y ago
      [deleted]
    - Jtsummers 6y ago
      > Code should have a hierarchical structure, so one could read it on the high level of abstraction and also zoom in gradually, as necessary I agree with this. Some of the best code I've read and written was done in this style. Properly separating out components into a hierarchy of modules. > this is what they usually mean by "code is the documentation" I disagree with this. I don't think this is what people mean at all, because I don't think that most people do the first part. If they did, there wouldn't be so many problems with "code is the documentation". But most code is not written in a clear hierarchical fashion. Logic is weirdly commingled, and depending on the language you have an assortment of low-level bookkeeping mixed with high-level logic. I think they literally just mean "code is the documentation". One of the best/worst programmers I ever worked with is a perfect example of this. He'd always insist on the "code is the documentation", and his code always worked. But his code was absolutely awful to read for anyone but him. By way of analogy, I don't have a file system for physical papers. I have a literal chronological (by access time) stack. No one but me can make use of it, but it's very effective for me because I have a really good memory (though not as good as it was 20 years ago, I don't actually do this anymore because I have to work with others). That's his code. No one else can go into it and actually understand it (at least not easily), but he can jump in and make exactly the necessary changes. The code is not the documentation until it's properly organized, and maybe not even then.
- gwd 6y ago
  > I find this is nonsense. Code is the best documentation Strangely, I find both gp and your claims to be nonsense. :-) I've definitely experienced what you've experienced -- until you actually have code, you don't know what works and what doesn't work. But it's frequently not at all obvious what code does, even in the normal case; and even code which looks obviously correct often has hidden complexities that you wouldn't have thought of. I find trying to explain in a comment why the code I've written is correct is pretty good in wheedling out all the ways in which it's not actually correct. So when things are really complicated, you need both: You need to have code that actually works, and you need to have text that attempts to prove that the code actually works.
  - brabel 6y ago
    > I find trying to explain in a comment why the code I've written is correct is pretty good in wheedling out all the ways in which it's not actually correct. I found that well written, expressive tests accomplish that really well. I use Spock[1] to write complex tests and I just can't recommend it enough if you're working with the JVM (Java, Kotlin, Groovy, Scala, Clojure). We have several thousands of Spock tests and it's amazing how they have scaled with us... they've grown to support extremely complex workflows that have nearly zero accidental complexity and are easily readable even if you have no experience with it. [1] http://spockframework.org http://spockframework.org
    - fulafel 6y ago
      With Clojure, are you writing tests in the Spock DSL (or is that Groovy?) or are you writing the tests in Clojure and importing Spock as a library and extending its classes etc?
      - brabel 6y ago
        Spock tests must be written in Groovy, but they can call helpers from any JVM language, so we normally have lots of test helpers (traits) which we use to write tests with one-liners per action/assertion. If you write your app in any JVM language, you can use Spock to t test it because Groovy really has excellent interop with Java, hence JVM languages in general.
- mrbald 6y ago
  "make sure it's something that can actually be checked" -- I'd love to find out about a sane (not purely academic, financially viable) way to do it. Since university days I know that a piece of paper is an irreplaceable tool - cheap and universal. I usually just draw it on paper, then code, then fix the code, then update the painting, and do it over again until both match each other and work. Never fails me.
qz2 6y ago
That's the key difference between forward engineering and hacking shit together. There is nothing wrong with prototypes but some people mistake them as production ready items because it looks like a whole load of work has been done.
mtzet 6y ago
I disagree in the general. It's very easy to write a spec that contradicts itself and is impossible to actually implement. Some things do have to be designed, and not just thrown together though. That may be through spec, but it could also be working things through on paper. Concurrency is certainly one of these. Other things need to be iterated on in code. I'd hate to play a platformer where the movement mechanics were specced out by a comitee before any code was made.

MaxBarraclough 6y ago

> formal specification Do you mean a written spec, or a proper formal specification? https://en.wikipedia.org/wiki/Formal_specification https://en.wikipedia.org/wiki/Formal_specification

xfer 6y ago
For concurrency related specs i was alluding to spin/TLA+.
- MaxBarraclough 6y ago
  Great, thanks for clarifying.