From 2a969a10c6cccc2652c4fe35ccfff83ba6a22839 Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Tue, 18 Jun 2019 11:20:05 -0300 Subject: [PATCH] Added the chapter about specs --- content/books/things-i-learnt/_index.md | 2 + content/books/things-i-learnt/intro/index.md | 7 ++++ .../books/things-i-learnt/spec-first/index.md | 40 +++++++++++++++++++ 3 files changed, 49 insertions(+) create mode 100644 content/books/things-i-learnt/spec-first/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index 82aeafa..3c20ffa 100644 --- a/content/books/things-i-learnt/_index.md +++ b/content/books/things-i-learnt/_index.md @@ -5,3 +5,5 @@ template = "section-contentless.html" +++ * [Intro](intro) +* Programming: + * [Spec First, Then Code](spec-first) diff --git a/content/books/things-i-learnt/intro/index.md b/content/books/things-i-learnt/intro/index.md index b50db8a..da178ea 100644 --- a/content/books/things-i-learnt/intro/index.md +++ b/content/books/things-i-learnt/intro/index.md @@ -42,4 +42,11 @@ properly and add some examples. And that's how the idea to write this "book" came to life. +One thing you must keep in mind here: *These are my options*. I understand +that not everything is so black and white as put here, and some people's +experiences may not match things here. Also, you get a bit cynical about +technology after 30 years. So... thread carefully, 'cause here be dragons. + [^1]: Yup, I'm guilty of that too. + +{{ chapters(next_chapter_link="spec-first", next_chapter_title="Spec First, The Code") }} diff --git a/content/books/things-i-learnt/spec-first/index.md b/content/books/things-i-learnt/spec-first/index.md new file mode 100644 index 0000000..3163b99 --- /dev/null +++ b/content/books/things-i-learnt/spec-first/index.md @@ -0,0 +1,40 @@ ++++ +title = "Things I Learnt The Hard Way - Spec First, Then Code" +date = 2019-06-18 + +[taxonomies] +tags = ["en-au", "books", "things i learnt", "specs", "code"] ++++ + +"Without requirements or design, programming is the art of adding bugs to an +empty text file." -- Louis Srygley + + + +If you don't know what you're trying to solve, you don't know what to code. + +A lot of times we have this feeling of "let me jump straight to the code". But +without understanding what problem you're trying to solve, you'd end up +writing a bunch of things that doesn't solve anything -- or, at least, +anything that _should_ be solved. + +So here is the point: Try to get a small spec on whatever you want to solve. +But be aware that even that spec may have to be thrown out, as the +understanding of the problem tend to grow as long as the project continue. + +Yes, it's paradoxical: You need a spec to know what to code to avoid coding +the wrong solution, but the spec may be wrong, so you _end up_ solving the +wrong solution anyway. So what's the point? The point is, the spec reflects +the understanding of a problem _at a certain point_: All you (and your team) +know is _there_. + +The times I stood longer looking at my own code wondering what to do next were +when we didn't have the next step defined: It was missing some point of the +solution or we didn't have the communication structures defined or something +of sorts. Usually, when that happened, I stumbled upon Twitter or Mastodon +instead of trying to solve the problem. So when you see yourself doing this +kind of stuff -- "I don't know what to do next, and I'm not sure if I'm done +with the current problem" -- then maybe it's time to stop and talk to other +people in the project to figure that out. + +{{ chapters(prev_chapter_link="intro", prev_chapter_title="Intro") }}