Browse code

First steps converting "Things I Learnt" into mdBook

Julio Biason authored on 27/08/2019 08:19:18
Showing 9 changed files

1 1
new file mode 100644
... ...
@@ -0,0 +1 @@
1
+book
0 2
new file mode 100644
... ...
@@ -0,0 +1,6 @@
1
+[book]
2
+authors = ["Julio Biason"]
3
+language = "en"
4
+multilingual = false
5
+src = "src"
6
+title = "Things I Learnt The Hard Way (In 30 Years of Software Development)"
0 7
new file mode 100644
... ...
@@ -0,0 +1,8 @@
1
+# Summary
2
+
3
+- [Intro](./intro.md)
4
+- [Disclaimer](./disclaimer.md)
5
+- [Programming](./programming/index.md)
6
+	- [Before You Start Writing Code](./programming/before.md)
7
+		- [Spec First, Then Code](./programming/spec-first.md)
8
+		- [Write Steps as Comments](./programming/steps-as-comments.md)
0 9
new file mode 100644
... ...
@@ -0,0 +1,34 @@
1
+# Disclaimer 
2
+
3
+There is one magical thing you need to know when reading this book: It's all
4
+personal opinion
5
+
6
+A lot of stuff I'm going to discuss throughout this book will come directly
7
+from my personal experience in several projects -- system applications, web
8
+backend, embedded, mobile, stream processing -- in several different languages
9
+-- C, C++, Python, Java, Clojure, Rust. And, because it comes from personal
10
+experience, everything reflects my own personal opinion on several subjects.
11
+
12
+Obviously, you don't need to agree with every single point. But I hope at
13
+least it will make you rethink a few subjects.
14
+
15
+Also, sometimes I may mention some examples that people who know me -- either
16
+worked with me, heard me complain about some project, inherit one of my
17
+projects, _I_ inherit one of the _their_ projects -- may recognized and think
18
+I'm attacking the author.
19
+
20
+I am not.
21
+
22
+We do mistakes. Sometimes we don't know the topic with are attacking,
23
+sometimes we don't have full specs, sometimes we don't have the time to write
24
+things properly in a crunchtime. And that's why some things don't look as
25
+pretty as they should. Heck, if you think I'm attacking the original author of
26
+some example, look back the stuff I wrote and you'll see things a lot worse.
27
+
28
+But I need the example. I have this hope that showing people a few mistakes
29
+can make things better. I want to show people how my opinion built over
30
+some subject. And, again, I'm in no way attacking the original author of the
31
+code. I may even call the code "stupid", but I'm not calling the author
32
+_stupid_.
33
+
34
+With that in mind...
0 35
new file mode 100644
... ...
@@ -0,0 +1,50 @@
1
+# Intro
2
+
3
+"Things I Learnt The Hard Way (In 30 Years of Software Development)" started
4
+as a simple sequence of toots (the same as "tweets", on
5
+[Mastodon](https://functional.cafe/@juliobiason) when I was thinking about a
6
+new presentation I could do.
7
+
8
+But why "a new presentation"?
9
+
10
+I go around my state with a group called
11
+"[Tchelinux](https://tchelinux.org/)": We usually go to universities and talk
12
+to people starting uni, explaining things about free/libre software and
13
+sometimes telling people about things they wouldn't normally see in the uni
14
+curriculum.
15
+
16
+One thing that annoys me is that there are very few presentations about "when
17
+things go wrong". All the presentations show prototypes or tell the good
18
+stuff, and hide all the wrong things that could happen[^1]. Obviously, after
19
+working 30 years in the field of software development, I saw my fair share of
20
+things going wrong -- sometimes in unimaginable piles of crap -- and I thought
21
+"maybe that's something people would like to hear".
22
+
23
+(And, to be completely honest, some of those piles of crap were my own fault.)
24
+
25
+And that's when the toot sequence started. Just before I noticed, I spent the
26
+whole day just posting this kind of stuff (fortunately, my pile of things in
27
+the "incoming" folder was a bit empty at the time) and it had 30 points, plus
28
+addenda and a few explanation points. That's when I decided to group all
29
+them in a single post.
30
+
31
+(Actually, I'm lying: Someone mentioned on Functional Café that I should make
32
+a blog post for making it easier to read.)
33
+
34
+All I thought when I grouped everything in a post was "this will make things
35
+easier for the people following the thread on Mastodon". But then the post
36
+appeared on Reddit. And Twitter. And HackerNews. And YCombinator. And none of
37
+those where mine.
38
+
39
+But here is the thing: Each point was limited by the toot size, which is 500
40
+characters. Sometimes that's not enough to expand the point, explain it
41
+properly and add some examples.
42
+
43
+And that's how the idea to write this "book" came to life.
44
+
45
+One thing you must keep in mind here: *These are my options*. I understand
46
+that not everything is so black and white as put here, and some people's
47
+experiences may not match things here. Also, you get a bit cynical about
48
+technology after 30 years. So... thread carefully, 'cause here be dragons.
49
+
50
+[^1]: Yup, I'm guilty of that too.
0 51
new file mode 100644
... ...
@@ -0,0 +1,4 @@
1
+# Before You Start Writing Code
2
+
3
+Before you sit in front of your computer and open your text editor/IDE to
4
+write code, maybe you should take a step back and come with some stuff.
0 5
new file mode 100644
... ...
@@ -0,0 +1,4 @@
1
+# Programming Tips
2
+
3
+I'm a software developer. I write code. So here are some of things I learnt
4
+about the craft.
0 5
new file mode 100644
... ...
@@ -0,0 +1 @@
1
+# Spec First, Then Code
0 2
new file mode 100644
... ...
@@ -0,0 +1,49 @@
1
+# Write Steps as Comments
2
+
3
+Don't know how to solve your problem? Write the steps as comments in your
4
+code.
5
+
6
+There you are, looking at the blank file wondering how you're going to solve
7
+that problem. Here is a tip:
8
+
9
+Take the spec you (or someone else) wrote. Break each point into a series of
10
+steps to reach the expected behaviour. You can even write on your natural
11
+language, if you don't speak English.
12
+
13
+Then fill the spaces between the comments with code.
14
+
15
+For example, if you have a spec of "connect to server X and retrieve
16
+everything there. Save the content in the database. Remember that server X API
17
+allow you can pass an ID (the last ID seen) and you can use it to not retrieve
18
+the same content again." Pretty simple, right?
19
+
20
+Writing this as comments, pointing the steps you need to make, you may end up
21
+with something like this:
22
+
23
+```
24
+// connect to server X
25
+// retrieve posts
26
+// send posts to the database
27
+```
28
+
29
+Ah, you forgot the part about the ID. No problem, you just have to add it in
30
+the proper places -- for example, it doesn't make sense to connect to the
31
+server before you have the last seen ID:
32
+
33
+```
34
+// open configuration file
35
+// get value of the last seen ID; if it doesn't exist, it's empty.
36
+// connect to server X
37
+// retrieve posts starting at the last seen ID
38
+// send posts to the database
39
+// save the last seen ID in the configuration file
40
+```
41
+
42
+Now it is "easy"[^1]: You just add the code after each comment.
43
+
44
+A better option is to change the comments into functions and, instead of
45
+writing the code between the comments, you write the functionality in the
46
+function themselves and keep a clean view of what your application does in the
47
+main code.
48
+
49
+[^1]: Yes, that was sarcastic.