7 ms·
This is interesting at the bottom of the readme file Jez also offered this interesting BRender anecdote in an email: When Sam Littlewood designed BRender,
by svag 4y ago
This is interesting at the bottom of the readme file
Jez also offered this interesting BRender anecdote in an email:
When Sam Littlewood designed BRender, he didn’t write the code. And then document it.
The way most things were built at the time.
First, he wrote the manual. The full documentation
That served as the spec. Then the coding started.
- johnchristopher 4y agoRight now, at work, I am getting insane with a task of re implementing some web forms that talk to shinier API. No documentation "just read the previous ruby server side validation code and put it on the js front-end". So I am hunting for hints and people to to be sure the code does what it intended to do. And I get cup sized eyes when asking for documentation :D.
- cfn 4y agoYou are lucky, I am reimplementing CRM functionality on a web api by looking at SQL Server Profiler!
- johnchristopher 4y agoHaha, wtf :D.
- teh_klev 4y agoHoley moley, that's just plain cruel.
- smaudet 4y agoWhy wouldn't you reach for a decompiler first? I guess perhaps you are working with some very obfuscated code, still if you are black box profiling code it might make sense to crack open that box as much as possible. Unless what you are working with is DRM-level "performs like cow dung in a blender" horrifically inefficient, I can't imagine it is obfuscated that badly. At any rate, hopefully you are paid well for it, reverse engineering is difficult, to say the least.
- cfn 4y agoThey have the source code but they need someone to sign off, etc, etc (I am an external contractor) and meanwhile I started by doing what I could and now am nearly finished. Decompiling the old app would be hard because it is a VB application.
- deleted 4y ago[deleted]
- kolme 4y agoThat's the _worst_ kind of specification. "It has to be like the old one, but with this differences". That means you have to study the old code, which is of course poorly documented and probably buggy; and then try to reproduce it in a sane way.
- exikyut 4y agoAlternative idea: keep running the same Ruby code. - https://github.com/ruby/ruby.wasm https://github.com/ruby/ruby.wasm (compile Ruby to WASM) - https://mame.github.io/emruby/ https://mame.github.io/emruby/ (example of Ruby compiled to WASM) - https://opalrb.com/ https://opalrb.com/ (compile a subset of Ruby to JS) This requires downloading several MB of code (and then caching it in-browser) so would be ideal for internal-only stuff.
- johnchristopher 4y agoPretty cool. (I changed the languages for privacy reasons but your solution still stands)
- exikyut 4y agoAh, well even if it's some super-obscure or internal thing, if it compiles down to C that doesn't mind POSIX you might still be able to Emscripten-ify it! (Part of my thinking with this solution is to broadcast "you are asking me to do something that requires a solution this complex to wrangle the problem space effectively" to try to fend off similar inanity in the future, admittedly, perhaps I'm being a bit optimistic/unrealistic heh.)
- Cthulhu_ 4y agoYeah I'm doing the same thing; I get by well enough with trying to read the old code and playing around with the old user interface, but there's hundreds of fields and thousands of features that I have to go through one at a time. Most validation is just a regular expression though, easy enough to port.
- avgDev 4y agoWe had an application running a business for 10 years. It started printing labels incorrectly. There was a bug in the code. The source code provided for the application was at least 5 years out of date. Documentation was null. Additionally, the variable names were TextBox1, TextBox2....etc. I decompiled the app, documented the UI and which variable is what. Rewrote the whole app. It was quite painful but good learning experience. I would love to do another one.
- magpi3 4y agoThis is an amazing, amazing skill. Do any university classes teach programmers how to think like this? Can it be taught?
- dranka 4y agoIt sounds a bit like the Waterfall model. It became highly unfashionable in the 90s, maybe even earlier.
- buescher 4y agoIt's really more of a proto-agile approach! I've never done the manual first personally, though I had a boss that had been on a project run that way early in his career who always wanted to do things that way again. The idea is to skip distilling requirements into specifications, engineering documentation, and user documentation. Instead you gather requirements AS user documentation, and only work backwards from there as necessary. Sort of like skipping all the specifications to V&V activities in a traditional systems engineering approach by writing tests first in test-driven-development.
- dranka 4y agoMy comparison to waterfall was a reductionistic take on the specifications up-front before coding starts aspect. If comparing it to the full waterfall process then it is definitely a fresh take!
- llampx 4y agoCan that really happen with Agile, which means requirements can change or new requirements can come in at any time?
- OwlsParlay 4y agoYou'd still start off with requirements - documentation - code, it's just on the understanding that any of these can change.
- 4y ago
- dusted 4y agoI've done some hobby projects this way, of course I've allowed myself to go back and adjust the documentation where the implementation would be easier or simpler from only slight alterations of the workflow. It's been very pleasant, and allowed me to make good sense of what I was doing and where I was going.
- walski 4y agoThe concept of "Readme Driven Development" [1] seems similar, but smaller in scope. I've actually found it very pragmatic/productive to, especially for smaller libraries, start with writing the Readme. 1: https://tom.preston-werner.com/2010/08/23/readme-driven-development.html https://tom.preston-werner.com/2010/08/23/readme-driven-deve...
- mkreis 4y agoThat reminds me of Amazon's method "working backwards": https://www.productplan.com/glossary/working-backward-amazon-method/ https://www.productplan.com/glossary/working-backward-amazon... You start e.g. with a press release and then make your way backwards to the user stories and backlog. It's a very useful approach to think big and focus on the problem instead of the many little issues that need to be solved. The problem is that programming is still knowledge work. That means you can not specify everything beforehand without doing the actual work. (Like writing a novel, which can not specified before.) The solution would imho be a good balance between description the big picture/desired result (good) and spec'ing out every little detail and screen in advance (bad).
- indigochill 4y agoI remember seeing a programming tutorial that used this approach as well fairly early in my software engineering education. I want to say it was part of the SICP MIT course but I could be confusing it with something else. It was pitched as something like "wishful thinking programming" IIRC. First you write the highest-level "business logic" code that you want to write with made-up constructs that have no implementation, then only once you've established that it feels good to write code using those constructs do you implement them. I remember this also being the same approach that was used in a CPU-building course I took (NAND 2 Tetris): start with the instruction set, then implement it.
- dr-neptune 4y agoWishful thinking is mentioned several times in SICP, both in terms of to be implemented functions and in separation of concerns. Oftentimes in the book, they will write out a function with reliance on a variety of other functions that haven't been written yet, but which show a blissfully declarative outline of exactly what the function does. Then you go and write the sub-functions. Looking at the code after is quite nice, but it takes a bit to wrap your head around writing large swaths of code that can't run -- especially when you're used to writing REPL-driven code and consistently checking/"testing" it
- astrange 4y ago
- Narann 4y agoBy some aspect this is how you write an API.
- samlittlewood 4y agoSome more detail on this: The starting point for BRender was a sequence of software rendering experiments that grew from 'never doing it like our hand coded asm real mode x86 renderers ever again'. There were various diversions, eg: an achingly beautiful plane sweep that only rendered the visible parts of each output scanline, whilst murdering the cache so comprehensively that there are likely still lines waiting to be filled even now. Fortunately, to get the FX Fighter team going with something stable whilst debugging continued, I knocked up a Z buffer implementation, and was given a sharp lesson on caching when it blew all the previous attempts away (notably with consistency of performance). Arriving at this point we figured there might be a product in it and looking at our own interaction with other libraries, it was clear that a manual was key to this. If I remember correctly, the API was a negotiation between myself proposing designs, and Crosbie Fitch documenting it - pushing back with ways to make things easier to explain. It worked out very well, and we took it into later Argonaut hardware projects. The hardware guys had enough tools to do frame capture and replay from various games/apps at a low level, so were not desperate for a full software stack. The clients had very particular views about how APIs should look, depending on planned uses, in house style, compatibility etc. We would negotiate the API documentation back and forth - including lots of sample code. This sample code was important, (and BRender would have benefited from more of this). I took lots of real use cases, then wrote proper code to implement them against the proposed APIs and included them in the docs as tutorial and example code. Importantly - they were a representative sampling of the anticipated uses (not just the easy ones), they were not 'handwavy' and included all appropriate resource management and error handling, and they had to read well on the page. As the API negotiation continued, so the examples and tutorials got updated. This process also had the benefit that we only started investing in client specific software development once the project had got enough momentum (typically committing hardware NRE).
- ArtWomb 4y ago"hand coded asm real mode x86 renderers" a more elegant weapon, from a more civilized age, may the forth be with you ;)
- CrosbieFitch 4y agoIs this really '4 days ago' as of 8-May-2022? If it is, "Hello Sam!"