Write steps as comments

content/books/things-i-learnt/_index.md

@@ -7,3 +7,4 @@ template = "section-contentless.html"
 * [Intro](intro)
 * Programming:
 	* [Spec First, Then Code](spec-first)
+	* [Write Steps as Comments](steps-as-comments)

content/books/things-i-learnt/intro/index.md

@@ -49,4 +49,4 @@ 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") }}
+{{ chapters(next_chapter_link="/books/things-i-learnt/spec-first", next_chapter_title="Spec First, The Code") }}

content/books/things-i-learnt/spec-first/index.md

@@ -37,4 +37,4 @@ 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") }}
+{{ chapters(prev_chapter_link="/books/things-i-learnt/intro", prev_chapter_title="Intro", next_chapter_link="/books/things-i-learnt/steps-as-comments", next_chapter_title="Write Steps as Comments") }}

content/books/things-i-learnt/steps-as-comments/index.md

@@ -0,0 +1,58 @@
++++
+title = "Things I Learnt The Hard Way - Write Steps as Comments"
+date = 2019-06-18
+
+[taxonomies]
+tags = ["en-au", "books", "things i learnt", "steps", "comments", "code"]
++++
+
+Don't know how to solve your problem? Write the steps as comments in your
+code.
+
+<!-- more -->
+
+There you are, looking at the blank file wondering how you're going to solve
+that problem. Here is a tip:
+
+Take the spec you (or someone else) wrote. Break each point into a series of
+steps to reach the expected content. You can even write on your natural
+language, if you don't speak English.
+
+Then fill the spaces between the comments with code.
+
+For example, if you have a spec of "connect to server X and retrieve
+everything there. You should save the content in the database. Remember that
+server X has an API that you can pass an ID (the last ID seen) and you can use
+it to not retrieve the same content again." Pretty simple, right?
+
+Now, writing this in comments, pointing the steps you need to make:
+
+```
+// connect to server X
+// retrieve posts
+// send posts to the database
+```
+
+Ah, you forgot the part about the ID. No problem, you just have to add it in
+the proper places -- for example, it doesn't make sense to connect to the
+server before you have the last seen ID:
+
+```
+// open configuration file
+// get value of the last seen ID; if it doesn't exist, it's empty.
+// connect to server X
+// retrieve posts starting at the last seen ID
+// send posts to the database
+// save the last seen ID in the configuration file
+```
+
+Now it is "easy"[^1]: You just add the code after each comment.
+
+A better option is to change the comments into functions and, instead of
+writing the code between the comments, you write the functionality in the
+function themselves and keep a clean view of what your application does in the
+main code.
+
+[^1]: Yes, that was sarcastic.
+
+{{ chapters(prev_chapter_link="/books/things-i-learnt/spec-first", prev_chapter_title="Specs First, Then Code") }}