diff --git a/things-i-learnt/src/SUMMARY.md b/things-i-learnt/src/SUMMARY.md index 67b0171..f1e1be2 100644 --- a/things-i-learnt/src/SUMMARY.md +++ b/things-i-learnt/src/SUMMARY.md @@ -6,3 +6,5 @@ - [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) + - [Gherkin Is Your Friend to Understand Expectations](./programming/gherkin.md) + - [Design Patters Are Used to Name Solution, Not Find Them](./programming/patterns-not-solutions.md) diff --git a/things-i-learnt/src/programming/gherkin.md b/things-i-learnt/src/programming/gherkin.md new file mode 100644 index 0000000..af193c1 --- /dev/null +++ b/things-i-learnt/src/programming/gherkin.md @@ -0,0 +1,46 @@ +# Gherkin Is Your Friend to Understand Expectations + +Gherkin is file format for writing behaviour tests (BDD). But it can also give +you some insights on what you should do. + +Alright, let's talk a bit about Gherkin: + +[Gherkin](https://en.wikipedia.org/wiki/Cucumber_(software)#Gherkin_language) +is a file format created for [Cucumber](https://en.wikipedia.org/wiki/Cucumber_(software)), +which describes scenarios, what's in them, what actions the user/system will +do and what's expected after those actions, in a very high level, allowing +people without programming experience can describe what's expected from the +system. + +Although Gherkin was born with Cucumber, it is now supported by a bunch of +programming languages, through external libraries. + +A typical Gherkin file may look something like this: + +* **Given that** _initial system environment_ +* **When** _action performed by the user or some external system_ +* **Then** _expected system environment_ + +Or, in a more concrete example: + +* **Given that** The system is retrieving all tweets liked by the user +* **When** It finds a tweet with an attachment +* **Then** The attachment should be saved along the tweet text + +Pretty simple, right? + +Now, why I'm mentioning this? + +Sometimes, specs are not the most clear source of information about what it is +expected from the system, and up can't think of [steps to do +so](/books/things-i-learnt/steps-as-comments). If you're confused about what +you should write, asking the person responsible for the request to write +something like Gherkin may give you some better insights about it. + +Obviously, it won't be complete. People tend to forget the error situations -- +like filling the name field with numbers, using characters in age fields, +tweets with no text and just attachments -- but at least with a Gherkin +description of the system, you can get a better picture of the whole. + +Also, you may not like to write specs. That's alright, you can replace them +with Gherkin anyway. diff --git a/things-i-learnt/src/programming/patterns-not-solutions.md b/things-i-learnt/src/programming/patterns-not-solutions.md new file mode 100644 index 0000000..1ac602c --- /dev/null +++ b/things-i-learnt/src/programming/patterns-not-solutions.md @@ -0,0 +1,28 @@ +# Design Patterns Are Used to Name Solution, Not Find Them + +Most of the times I saw design patterns being applied, they were applied as a +way to find a solution, so you end up twisting a solution -- and, sometimes, +the problem it self -- to fit the pattern. + +My guess is that the heavy use of "let's apply _this_ design pattern" before +even understanding the problem -- or even trying to solve it -- comes as a +form of [cargo cult](/books/things-i-learnt/cargo-cult): "We saw that people +used this pattern and solved their problem, so let's use it too and it will +solve our problem". Or, worse: "Design pattern is described by _Famous +Person_, so we must use it". + +Here is the thing: Design pattern should _not_ be used as a way to find +solution to any problems. You may use some of them as base for your solution, +but you must focus on the _problem_, not the _pattern_. + +"Do a visitor pattern will solve this?" is the wrong question. "What should we +do to solve our problem?" is the real question. Once you went there and solved +the problem you may look back and see if it is a visitor pattern -- or whatever +pattern. If it doesn't, that's alright, 'cause you _solved the problem_. If it +did... well, congratulations, you now know how to name your solution. + +I've seen this happening a lot: People have a problem; people decided to use a +pattern; the pattern doesn't actually solve the problem (not in the 100% mark, +but above 50%); what happens then is that people start twisting the problem to +fit the pattern or, worse, add new layers to transform the problem into the +pattern. diff --git a/things-i-learnt/src/programming/spec-first.md b/things-i-learnt/src/programming/spec-first.md index 4be53a2..3efadeb 100644 --- a/things-i-learnt/src/programming/spec-first.md +++ b/things-i-learnt/src/programming/spec-first.md @@ -1 +1,41 @@ # Spec First, Then 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](/books/things-i-learnt/throw-away), 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. + +Another way to think this: Erik Deitrich have a post about [Don’t Learn to +Code — Learn to Automate](https://daedtech.com/dont-learn-to-code-learn-to-automate/), +something I can get behind 'cause most of us, when doing stuff, think "I need +to do this, then I pick that thingy and put it there and from there I do this +other work". Basically, we create mental models of specs, step by step, on +what we need to do. And, from there, it may be even simpler, 'cause now all +you need to learn is "First, how I do this; Ok, got it, now I get the result +from this and put there" and so on. You can even have a learning path, if +you're a beginner.