commit 982777276e25bdf0ad2c442ce60577459c3d4347 Author: Julio Biason Date: Tue Aug 27 12:19:18 2019 -0300 First steps converting "Things I Learnt" into mdBook diff --git a/things-i-learnt/.gitignore b/things-i-learnt/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/things-i-learnt/.gitignore @@ -0,0 +1 @@ +book diff --git a/things-i-learnt/book.toml b/things-i-learnt/book.toml new file mode 100644 index 0000000..2ed7c34 --- /dev/null +++ b/things-i-learnt/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Julio Biason"] +language = "en" +multilingual = false +src = "src" +title = "Things I Learnt The Hard Way (In 30 Years of Software Development)" diff --git a/things-i-learnt/src/SUMMARY.md b/things-i-learnt/src/SUMMARY.md new file mode 100644 index 0000000..67b0171 --- /dev/null +++ b/things-i-learnt/src/SUMMARY.md @@ -0,0 +1,8 @@ +# Summary + +- [Intro](./intro.md) +- [Disclaimer](./disclaimer.md) +- [Programming](./programming/index.md) + - [Before You Start Writing Code](./programming/before.md) + - [Spec First, Then Code](./programming/spec-first.md) + - [Write Steps as Comments](./programming/steps-as-comments.md) diff --git a/things-i-learnt/src/disclaimer.md b/things-i-learnt/src/disclaimer.md new file mode 100644 index 0000000..a3425df --- /dev/null +++ b/things-i-learnt/src/disclaimer.md @@ -0,0 +1,34 @@ +# Disclaimer + +There is one magical thing you need to know when reading this book: It's all +personal opinion + +A lot of stuff I'm going to discuss throughout this book will come directly +from my personal experience in several projects -- system applications, web +backend, embedded, mobile, stream processing -- in several different languages +-- C, C++, Python, Java, Clojure, Rust. And, because it comes from personal +experience, everything reflects my own personal opinion on several subjects. + +Obviously, you don't need to agree with every single point. But I hope at +least it will make you rethink a few subjects. + +Also, sometimes I may mention some examples that people who know me -- either +worked with me, heard me complain about some project, inherit one of my +projects, _I_ inherit one of the _their_ projects -- may recognized and think +I'm attacking the author. + +I am not. + +We do mistakes. Sometimes we don't know the topic with are attacking, +sometimes we don't have full specs, sometimes we don't have the time to write +things properly in a crunchtime. And that's why some things don't look as +pretty as they should. Heck, if you think I'm attacking the original author of +some example, look back the stuff I wrote and you'll see things a lot worse. + +But I need the example. I have this hope that showing people a few mistakes +can make things better. I want to show people how my opinion built over +some subject. And, again, I'm in no way attacking the original author of the +code. I may even call the code "stupid", but I'm not calling the author +_stupid_. + +With that in mind... diff --git a/things-i-learnt/src/intro.md b/things-i-learnt/src/intro.md new file mode 100644 index 0000000..98bf200 --- /dev/null +++ b/things-i-learnt/src/intro.md @@ -0,0 +1,50 @@ +# Intro + +"Things I Learnt The Hard Way (In 30 Years of Software Development)" started +as a simple sequence of toots (the same as "tweets", on +[Mastodon](https://functional.cafe/@juliobiason) when I was thinking about a +new presentation I could do. + +But why "a new presentation"? + +I go around my state with a group called +"[Tchelinux](https://tchelinux.org/)": We usually go to universities and talk +to people starting uni, explaining things about free/libre software and +sometimes telling people about things they wouldn't normally see in the uni +curriculum. + +One thing that annoys me is that there are very few presentations about "when +things go wrong". All the presentations show prototypes or tell the good +stuff, and hide all the wrong things that could happen[^1]. Obviously, after +working 30 years in the field of software development, I saw my fair share of +things going wrong -- sometimes in unimaginable piles of crap -- and I thought +"maybe that's something people would like to hear". + +(And, to be completely honest, some of those piles of crap were my own fault.) + +And that's when the toot sequence started. Just before I noticed, I spent the +whole day just posting this kind of stuff (fortunately, my pile of things in +the "incoming" folder was a bit empty at the time) and it had 30 points, plus +addenda and a few explanation points. That's when I decided to group all +them in a single post. + +(Actually, I'm lying: Someone mentioned on Functional Café that I should make +a blog post for making it easier to read.) + +All I thought when I grouped everything in a post was "this will make things +easier for the people following the thread on Mastodon". But then the post +appeared on Reddit. And Twitter. And HackerNews. And YCombinator. And none of +those where mine. + +But here is the thing: Each point was limited by the toot size, which is 500 +characters. Sometimes that's not enough to expand the point, explain it +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. diff --git a/things-i-learnt/src/programming/before.md b/things-i-learnt/src/programming/before.md new file mode 100644 index 0000000..5178efc --- /dev/null +++ b/things-i-learnt/src/programming/before.md @@ -0,0 +1,4 @@ +# Before You Start Writing Code + +Before you sit in front of your computer and open your text editor/IDE to +write code, maybe you should take a step back and come with some stuff. diff --git a/things-i-learnt/src/programming/index.md b/things-i-learnt/src/programming/index.md new file mode 100644 index 0000000..f09e920 --- /dev/null +++ b/things-i-learnt/src/programming/index.md @@ -0,0 +1,4 @@ +# Programming Tips + +I'm a software developer. I write code. So here are some of things I learnt +about the craft. diff --git a/things-i-learnt/src/programming/spec-first.md b/things-i-learnt/src/programming/spec-first.md new file mode 100644 index 0000000..4be53a2 --- /dev/null +++ b/things-i-learnt/src/programming/spec-first.md @@ -0,0 +1 @@ +# Spec First, Then Code diff --git a/things-i-learnt/src/programming/steps-as-comments.md b/things-i-learnt/src/programming/steps-as-comments.md new file mode 100644 index 0000000..14ca0ee --- /dev/null +++ b/things-i-learnt/src/programming/steps-as-comments.md @@ -0,0 +1,49 @@ +# Write Steps as Comments + +Don't know how to solve your problem? Write the steps as comments in your +code. + +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 behaviour. 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. Save the content in the database. Remember that server X API +allow you can pass an ID (the last ID seen) and you can use it to not retrieve +the same content again." Pretty simple, right? + +Writing this as comments, pointing the steps you need to make, you may end up +with something like this: + +``` +// 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.