Executable Documentation for everyone (even you)
This is a modal window.
The media could not be loaded, either because the server or network failed or because the format is not supported.
Formal Metadata
| Title |
| |
| Title of Series | ||
| Part Number | 17 | |
| Number of Parts | 59 | |
| Author | ||
| License | CC Attribution - NonCommercial 2.0 Germany: You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor. | |
| Identifiers | 10.5446/19631 (DOI) | |
| Publisher | ||
| Release Date | ||
| Language |
Content Metadata
| Subject Area | ||
| Genre | ||
| Abstract |
| |
| Keywords |
FrOSCon 201417 / 59
1
2
3
4
8
11
21
23
26
29
30
34
35
36
37
38
39
41
42
43
45
46
50
52
53
54
56
57
58
00:00
Open sourceOpen setFreewareCodeSoftware testing2 (number)Server (computing)Moment (mathematics)Multiplication signOcean currentCodeCASE <Informatik>BitSoftware engineeringAutomationSoftware developerSoftware frameworkSoftwareElectronic program guideWeb pageProjective planeComputer fileDifferent (Kate Ryan album)MathematicsParsingCondition number1 (number)Term (mathematics)Musical ensembleRight angleDigital electronics3 (number)Disk read-and-write headTwitterThermal radiationError messageWeb 2.0Reading (process)Inverter (logic gate)Revision controlSlide ruleXMLUML
07:41
Factory (trading post)Router (computing)Interior (topology)Boilerplate (text)Error messageQuicksortSign (mathematics)Computer programmingProgrammer (hardware)Reverse engineeringGoodness of fitLogicSoftware frameworkHazard (2005 film)Medical imagingSoftware bugSoftware developerNatural languageFunctional (mathematics)CircleSoftware testingPhysical systemAreaMultiplication signFormal languageSubsetLibrary (computing)Dependent and independent variablesMoment (mathematics)Line (geometry)Right angleTerm (mathematics)WordProcess (computing)CodeClient (computing)Router (computing)Student's t-testDifferent (Kate Ryan album)Open sourceQuery languageFreeware1 (number)Point (geometry)GodWritingInterface (computing)Row (database)AutomationXMLUML
15:14
Software testingMereologyInstance (computer science)Level (video gaming)Latent heatUnit testingWordFormal languageOrder (biology)Functional (mathematics)Point (geometry)Software developerPhysical systemPresentation of a groupInternet service providerTelecommunicationForm (programming)Programmer (hardware)Term (mathematics)Different (Kate Ryan album)AuthorizationNeuroinformatikDescriptive statisticsGroup actionTriangleElectronic program guideMultiplication signDecision tree learningInterface (computing)FreewareCASE <Informatik>Strategy gameLogic gateGoodness of fitAutomationAbstractionBoss CorporationPlastikkarteRight angle
22:47
Decision tree learningVirtual machineFunction (mathematics)Physical systemVariable (mathematics)Social classCodeStandard deviationWordData structureFitness functionTable (information)Projective planeProcess (computing)Programming languageRight angleUnit testingCodeComputer programmingOrder (biology)Client (computing)outputPositional notationPerspective (visual)SubsetCASE <Informatik>Product (business)Function (mathematics)QuicksortDescriptive statisticsMultiplication signSoftware testingPlastikkarteINTEGRALGoodness of fitFile formatInstance (computer science)Data managementSpeech synthesisVirtual machineDisk read-and-write headComputer configurationExecution unitMathematicsLatent heatData miningLine (geometry)FreewareJava appletPublic key certificateSimilarity (geometry)Mixed realityProgrammer (hardware)2 (number)
30:20
Term (mathematics)Online helpProjective planeProcess (computing)Right angleCovering spaceSoftwareComputer animation
31:16
Reverse engineeringVirtual machineSource codeMultiplication signSoftwareRule of inferenceArithmetic meanComputer fileUniqueness quantificationBitWeb pageProblemorientierte ProgrammierspracheCodeLatent heatSoftware testingMedical imagingOpen sourceRepository (publishing)Goodness of fitRight angleComputer programmingPerspective (visual)Web browserSingle-precision floating-point formatSoftware developerError messageMereologyPhysical systemFormal languageOrder (biology)Different (Kate Ryan album)AreaInstance (computer science)WebsiteProduct (business)Projective planeWordSound effectProcess (computing)NeuroinformatikReading (process)NP-hardTerm (mathematics)Doubling the cubeFunction (mathematics)System callEmail2 (number)
39:32
System callConstructor (object-oriented programming)Interface (computing)AbstractionSocial classHecke operatorGame theoryConvex hullSoftware testingProjective planeFunctional (mathematics)Electronic visual displaySystem callComputer fileCategory of beingDescriptive statisticsSpacetimeSocial classParameter (computer programming)Field (computer science)Execution unitPhysical systemOrder (biology)CodeSheaf (mathematics)Dependent and independent variablesDemo (music)Latent heatInjektivitätPerspective (visual)Bit error rateCASE <Informatik>Library (computing)Server (computing)WordTraffic reportingState of matterSinc functionNeuroinformatikGraph coloringMereologyPoint (geometry)Power (physics)QuicksortSet (mathematics)NumberMessage passingForm (programming)Programmer (hardware)Spectrum (functional analysis)Source codeXML
46:23
CASE <Informatik>ParsingGroup actionSampling (statistics)Function (mathematics)Software testingUnit testingCuboidSoftware developerTelecommunicationStaff (military)Extreme programmingForm (programming)Term (mathematics)Arithmetic meanObject (grammar)Boss CorporationDifferent (Kate Ryan album)Element (mathematics)CodeExtension (kinesiology)Computer programmingWordReading (process)Goodness of fitFrustrationFile formatLevel (video gaming)Physical systemAbstractionLatent heatProduct (business)Power (physics)INTEGRALSocial classCodePhysical lawContent (media)Student's t-testDemo (music)Integrated development environmentPresentation of a groupMultiplication signLink (knot theory)Right angleCache (computing)MereologyBinary decision diagram
52:12
Interface (computing)Constructor (object-oriented programming)CodeExtreme programmingSoftware testingKeilförmige AnordnungSoftware developerSoftware testingCodierung <Programmierung>Domain nameDifferent (Kate Ryan album)Goodness of fitComputer programmingExpert systemWordLatent heatCASE <Informatik>Formal languageMathematicsLibrary (computing)CodeBitEscape characterSocial classWritingPatch (Unix)MereologyProgrammer (hardware)
55:13
Computer animation
Transcript: English(auto-generated)
00:08
So, everybody having a good time at the FrostCon? Enjoying yourself? Nice. So, welcome to my talk. It's called executable documentation
00:21
for everybody, even for you. So, I want to show a couple of things about executable documentation, what it is and so on. But first of all, I want to know about you. Like who has never heard that term? Who doesn't have any connotations with it? Okay. So, that's quite a bit.
00:41
So, that's like half, no less. Okay. Maybe a third of the people who just want to know what the hell I'm talking about. That's good. The rest of you, some hands who has heard of it, or like who's, okay. Only one, two, three. Okay. Yeah, like, okay.
01:01
Who thinks, well, I mean, there's nothing less than heard of it, you know. So, and who's actually using it, or in his company and his projects? Okay. Yeah, it depends on what it means. Okay. So, maybe I'll ask the question later again,
01:21
and then you can tell me if you're using it the same way that I see it. Because it means a couple of different things. So, I'm going to do two things. First of all, I'm going to explain what I think it is, or what my definition of this whole executable documentation thing is. So, I give you the why, how, and what of it.
01:42
And then the second thing is, I'm going to present you Docs, which is a publishing tool I wrote for exactly this, for executable documentation. So, first, a little bit about me. That's me, this guy. Maybe I should draw my head, and then people recognize better.
02:02
My name is Nicholas Martens. I'm a freelancing software engineer and coach now in Berlin. Anybody from Berlin here? Oh, yeah. The whole left side of the site. So, yeah. I'm from the city, and you can find me on Twitter,
02:20
or on the web, or also on GitHub, if you're looking for me, but you can also find me right here at the moment. I'm also co-organizing a coding dojo in Berlin. So, the people from Berlin, if you ever wanted to know what a coding dojo is, so just check it out. It's next Thursday, it's coming up,
02:42
and everybody who's ever in Berlin just drop by, it's really fun always. So, that's what I'm doing, and let me tell you the story of why I'm doing this talk, like why this is important to me, or how this all started. I have two big topics.
03:04
One is software design, and the other one is testing. So, I'm really into those two things, and when I say testing, of course, I mean automated testing, because well, I'm a developer, developers are lazy, and I hate doing stuff manually. Coding is hard enough. I don't want to do unnecessary testing. So, I try to automate as much as possible,
03:23
and because I also have a strong case of the Not Invented Here syndrome, like most developers, I suppose, I needed to do my own mocking framework, because there aren't enough mocking frameworks for PHP at the moment, or ever. So, I needed to do another one.
03:40
I called it Mockster, and this is where it all started. Actually, I put a lot of effort into this project, because we also used it at ResearchGate, where it was working, and so, I wanted to make this really nice. So, I put a lot of effort into documentation, right, because documentation is very important.
04:00
If anybody was here yesterday morning, and saw the talk from Cora, he was having a lot of issues with badly documented projects. So, I didn't want anybody to have this problem. So, I put a lot of effort into documentation. So, I made a readme on GitHub. This is what you do nowadays. I wrote the main features,
04:21
like why this is better than all the other mocking frameworks, because it clearly is, it wouldn't exist otherwise. I wrote an installation guide. I wrote a quick start, where you can just copy and paste that code, basically, and it should work, and I even wrote,
04:42
this is a very long, basic usage, so it's like three pages, four pages long, how to use it and everything, and I was very happy with myself. It was the first project I did, mostly for myself, that I actually documented that well, so I was quite content, except that it was wrong. The codes I put in the example was not right,
05:04
because I just forgot to update some API changes I did, and it wasn't in the documentation anymore, so, yeah, outdated documentation. Anybody ever had the problem of outdated documentation? Who's never had the problem of outdated documentation?
05:21
Really? Okay. Okay. You just avoid it altogether, so there's no, very nice. So, yeah, I had the same problem, actually, somebody pointed out to me, it's like, oh, yeah, thank you for doing this nice, basic usage and everything, but it's actually, it's a parsing error.
05:41
This method doesn't exist, and I'm like, oh, that sucks. So, I started thinking what you can do, and I actually had an idea, and this is where this all started. I was like, let's take all this code from the documentation and put it into a PHP file, because then I can just make sure that I can just ask the parser, is this right or not?
06:04
And, of course, I didn't want to lose the nice comments I wrote, so I put them in the PHP file as well, as comments, obviously, and that's it. That's the executable documentation, because you still have the documentation of the project, and now you can run it. So, you can do away with the readme.
06:21
I just deleted it all. I mean, it's still there, because revisions and everything, but it's not in the current version, and I'm just executing this nice, little PHP file. It's executable now. I actually put it in my test folder, and let the CI server take care of it. So, now every time I see this little green light going on,
06:44
I know, okay, everything is all right. This actually still passes, and if I ever do the same mistake again, this will turn red. Never happened since then, but it might. So, I know if the documentation is still up to date or not, of course, for all the code.
07:00
The comments are still static, but they're not that important if you want to make it running. So, I was happy again, and that's it. That's executable documentation. Is this running away from, what are you doing? Yeah, it's different. Okay, you have to tell me later how it's yours. So, this is, yeah, definitely.
07:23
So, this is how I do it. This was very fun, and I'm gonna go a little bit into code now. Who's a developer here, writing code for a living? Who's not? Almost, okay. So, sorry about code. Even more sorry that it's cut off at the left side.
07:42
But it's PHP, you just have to imagine a bunch of dollar signs here. So, I cut them out. That's bad. You can still read it. So, this is how it looks like. This is the code of my mocking framework. Don't get into that, but I just wanted to show you how this is actually looking like.
08:02
So, it's validating the syntax now. If I ever make a syntax error, if I just make a spelling error, or so on, it will turn red, and I will know it. But, then I started noticing that I can even do more, because I can also validate the functionality of this mocking framework. I can just say, okay, why don't I actually
08:20
do call the foo method, and then assert, in the end, if the two calls, the was called with, and the was called with bus, if they return the right thing, okay? Because, it's still documenting how to use the library, and it's also validating the functionality.
08:41
And, a couple of people will say now, hey, I know what this is. This is a test. This is an automated test, right? And, yeah, that's true. It works both ways. Usually, I tell people, write your automated test, and you get your documentation for free. But, this way, it just happened the other way around this time. I wrote the documentation, and suddenly, I had a test.
09:00
But, because they're interchangeable, this actually works. So, yeah, they're just the same thing, basically, documentation and testing. And now, I have to prove that it works both ways. Very nice. So, this obviously works, is very easy with libraries, because, well, the client of your library is a program,
09:20
so it's really easy to write another program, which is an automated test, to use that library, right? So, this is easy. The same goes for public APIs, because they have other programs as clients, as well. So, I wanted to do it for APIs, as well, I have. And, I think, for APIs, it's especially important,
09:42
because, well, I've been working a lot with public APIs, with HTTP, like RESTful stuff, and it's usually terribly documented. Anybody else has this problem with public APIs? I mean, they're just never completely documented.
10:00
Usually, exactly this thing I need is not in the documentation, then I have to reverse engineer how this whole thing works. I mean, thank God it's open source, usually, so I can do that, but it's still a hassle. So, I thought, why don't I just use the same approach for APIs? I will have an executable documentation of this thing,
10:22
I will know if it works, and I'll be happy. So, and this can be done very easily. You just, here, I just request some query from the endpoint, foo bar, and I expect this answer with some data. It's a very imaginative, not doing much,
10:44
this little API, but you just can do it like this. And, of course, here, we have a lot of unnecessary boilerplate code, so to say. We have this router, which, of course, here is already instantiated, but we need to get it from somewhere,
11:00
and then we have this assertEquals and everything. And this is not very readable. I mean, for fellow developers, it is, but what if somebody else wants to understand it? What if some non-technical stakeholder wants to know how this API works? And then, you cannot show him this and be like, okay, this is how it works.
11:20
You know, it's very easy to understand. And he'll be like, what's this dollar sign doing there? Is this money? Or like, so this will confuse most non-technical or even non-PHP programmers. So, there's a really easy trick. You just wrap these ugly methods with nice methods. You just call it, when I request some query,
11:43
you have to fill in the gap from foo bar, then the response should be some data. And now, I didn't do much. I just wrapped this one line in another line, but now it's suddenly readable. And the other nice thing is that it's using
12:00
a natural language and also an ubiquitous language. Do you actually pronounce it like that? I never pronounce it. Ubiquitous, I think so. Meaning that everybody, this is a language everybody understands, everybody knows how to use it. And you have a good chance that your non-technical stakeholder
12:21
at least knows what a request is and what a response is, because if he's interested into APIs, he needs to know those two things at least. But he doesn't need to know what a router is or what the job of a router is. So, I used different words, I changed the language, and this is a lot more readable.
12:41
And with this little trick, you can now not only write documentation for APIs or libraries, you can just write it for everything, for any program. You want any program that does anything. And now I run full circle, and you might have heard this before.
13:02
This is exactly what behavior-driven development is. But approach from the other side, you start with the documentation and you end up with specifying your whole system suddenly. So, who knows who's familiar with behavior-driven development? Okay, that's not,
13:21
who's heard example-driven development before? One, you've heard it? Who's familiar or who has heard acceptance-test-driven development? No? And how about agile testing? These are, yeah, okay. So, I didn't make up these words.
13:41
These, they exist, they're just not very popular. I guess behavior-driven development is by far the most popular term for this. To me, they all mean the same thing. They all, they're just describing a system, using examples, and specifying it this way.
14:01
I actually prefer the term, oh yeah, good thing I put this there. I have, I don't like behavior-driven development, the word or the term, because people, I've seen a lot of bad practices about it. So, who's, usually people, when they say we're doing behavior-driven development, it means we're writing slow UI tests.
14:24
Who's testing through the UI? Like, with Selenio? You have to, okay. Do you enjoy it? You?
14:41
Yeah, and probably not so fast, right? You, yeah, you're recording. Yeah. Well, I'm totally on the side with Uncle Bob when he says that don't test through the UI,
15:00
only if you have to. If you wanna test the UI itself, then you have to, obviously. But if you wanna test any policies, any business logic, don't use the UI. It's the worst interface you can use. It's very fragile, the tests usually,
15:20
I mean, you're probably facing all these problems. The tests, they break easily. They break for reasons that have nothing to do with the thing that you're testing, because there's just too much in between. So, when I'm talking about these things, please don't think about Cucumber and Selenium and browser-based automated testing.
15:42
This is not what I mean. I mean, I'm talking about what I showed before, which is just describing functionalities in terms that everybody understand in a ubiquitous language. And this is why I'm usually not using behavior-driven development, but I'm talking about specification by example.
16:00
I like that term a lot better, and so I refer to it with this term from now on, but you can just substitute it in your brain if you don't like that term. You can use any of the other five that you want. We'll understand each other. So, I like specification by example because it has this word specification in it, which I think it's what really comes down to everything.
16:23
You have this interchangeability of tests and documentation. They're basically the same thing, and specification is the same thing as well. It's just it comes beforehand. You describe the system before you build it. Documentation describes the system after you build it, and tests describe the system in order to validate the functionality.
16:42
But it's just all descriptions of the system. So, usually it goes the other way around. Usually, you start with the specification, then implement it as a test, as an automated test, and then in the end, you get the documentation kind of for free because it's the same thing. But it's not that easy because you need a language.
17:03
You need a form of description that fits all these three needs, and they're quite different. In specification, sometimes you're not really sure how you're gonna do it, so you cannot describe it in a very detailed way. You have to describe it kind of abstractly.
17:21
And in tests, obviously, you have to be very specific because you wanna automate them, so they need to be very close to the system you're testing language-wise. And in documentation, you have the system, so you can rely on it. You can say, we do this and do this, and then comes out. So, language usually is different,
17:42
but there's a way to unify these three, which is examples. And this is why I like the term specification by example because it has the two main points of this whole approach which behavior-driven development doesn't have, because it has nothing to do with behavior-driven.
18:00
It means driven by behavior. I never really got it. Dan North is not happy with this term anymore, neither, and he came up with it. But examples is the main point because, as it turns out, it's a really nice tool to communicate with each other. And I put here on the left side, on the right side is the developer guy, okay, stereotype,
18:23
and the left side is the business guy stereotype, so he was, obviously. And these two parties have, a lot of times, trouble understanding each other because they speak different languages, almost. They have different concerns. Programmers, they're concerned about the detail,
18:41
all the ackee that they really love, getting their hands dirty and stuff, usually. And business people, they have to think about money, mostly, how to make money, how to contain money, how to strategy and stuff like that. Very, very different levels. So communication is hard. And if we use examples,
19:01
or that's the idea behind specification by example, in order to bridge this communication gap. And an example is just that. We already had it. When I request some query, then I should get some data. This is just, this is a very simple example. So it's not hard to formulate these, but it's really hard to come up with these.
19:21
And we've been doing that for a year or so at the research gate at the company I was working, and it turns out that's the biggest problem, to come up with good, key examples. And the concept of key example works kind of like this. Let's say you wanna describe this triangle. Instead of just drawing the whole triangle,
19:42
you can also just concentrate on these edges, and you still have the triangle specified there, and you can almost see it visually, right? But you only concentrate on the important things, on the edges, let's say. Don't take that literally, because if you only use edge cases, that's not a good specification either.
20:00
But it kind of works like this. But still, that's by far the hardest part. Who's using behavior-driven development, or specification by example, any of that approach in developing regularly? Very, just one, two? Okay, three. Is it like, how's your experience
20:21
with coming up with examples? Okay, many what?
20:46
Ah, helper. So you're saying that you're using it for UI testing mostly, so you don't come up with the examples, it's more like QA, so you click through it, it's the normal usage of the system you're testing.
21:02
You're automating. Okay. Yeah, but writing unit tests with data providers, that's very close to it. It's just that the formulation is different, the language, the words you're using is different, but the approach is very similar, right?
21:23
But that's exactly the difference, is unit tests are usually written for programmers, and these tests, they're written for everybody, so everybody should understand them, and this is why I like it. So you can combine these two things. I just wanna show you what I mean with examples,
21:42
so I'm gonna give you examples of examples, and let's say we're working at Amazon or some merchandise company, and this is us, we're like the programmers, and our boss comes to us and is like, you know, I have an idea. Let's give free delivery to all the VIP customers,
22:01
so we have more incentive for VIP customers. But let's say only four or five articles, and only if it's books, right? And then he goes like, bye, thanks. And you're like, what should I do now? And this is not even that far-fetched, like in my experience. A lot of times, you really just get a little sheet,
22:22
I mean, everybody's crazy about these user stories now, and they're supposed to specify the whole thing, like you write on one tiny card what it's supposed to do, and then you just do it, doesn't work. So let's describe the same thing with examples.
22:41
First example would be a VIP customer with five books in the card gets free delivery. That's like the canonical case. But a VIP customer with four books in the card doesn't get free delivery, obviously. And a regular customer with five books doesn't get free delivery neither, because it's only for VIP customers,
23:00
but if he has five washing machines in his card, he's not supposed to get free delivery neither. So that's actually something that wasn't specified before, right? Because you only said, okay, with five articles, but only books, but you weren't sure, for example, about this case, like if he has five books and a washing machine, should he still get free delivery or not?
23:22
Or should he get free delivery for the books, but not for the washing machine? What should we do in this case? And this is the nice thing about writing examples like that, that you actually start thinking about it in this detailed way, and you can communicate with your client
23:40
about edge cases like this, and you actually come up with them way faster than when you just go down coding, because then you find these edge cases while coding, and this way you find them beforehand, which is, in my experience, the biggest advantage about this approach. This is very similar.
24:02
Very good, this is exactly the same thing as the scenarios you have in Gherkin, but I didn't wanna use the buzzwords yet, but this is exactly the same thing. Who knows Gherkin, this whole cucumber? Okay, so don't worry, you'll see it later.
24:23
What this is. Well, now you have these nice examples, and you can put them in a structure. You can, for example, put them in a table. You can just say, okay, let's have a column for the customer type,
24:40
what his order is, and what the delivery should be. So you have the typical input-output description of a system, and every system can be described using his input and his output. This is what the system is by definition. And then you can just fill up the table. You can say, okay, VIP customer with five books should be free, VIP with four books
25:00
should not be free, and so on. Just what I wrote down and sent in this before. And so you just, you see you have three variables, or three, yeah, two input variable, one output variable, and you can use tables, and people are doing this, for example, fitness, or fit, is a tool that does that.
25:21
It's more like Java people. Anybody using fit or fitness for that sort of stuff? Okay, you're really doing everything, are you?
25:43
So you're mixing acceptance tests and unit tests. And for integration tests or acceptance tests, you use this way. And this is a really nice format,
26:01
because you can see it, you can read it very easily, you can see if something is wrong and why, but it's not very flexible. That's why I prefer sentences, also because I can write them in code, like this, and it's way more flexible. So you just write, you just come up with these helper methods, as you say, but they're okay, they're totally fine,
26:21
because they help you. You just write, given I am a VIP customer, and given I have five books in my basket, so this is PHP, so we cannot have any infix notation, so we have to do it like this. When I check my delivery options, then the delivery should be free. And this describes this scenario exactly,
26:42
and also it's very flexible. You just have to write a couple of methods, but that's not hard, right? We do this all the time. And they're not even that hard to implement. So this is like the business perspective, you just, and by the way, I've been using exactly this, and I've been showing the business stakeholders
27:02
of ResearchGate this code, and they were not very happy in the beginning, but after two or three weeks, they actually started being able to read it, and they could read it just as well as anything else, even with this weird notation of having replaced infix. They were fine with it, so this actually worked. And I was quite surprised by it,
27:21
because I thought I'd never get them to read code, but they did. They were in-house, they were the product managers. Yeah, that's why I could try these weird experiments. I don't think you can do that with external customers, be like, here, read this code. Yeah, okay, well.
27:43
Yeah, but I have a better solution, as you'll see in a second. So just for, if anybody's interested in that, like how you would actually implement these methods, you fake the inputs as good as you can, or you just use real entities, like the customer,
28:02
then you make them VIP, and in the books in my basket method, you create a basket instance and just fill it with books. Really, really straightforward stuff. Then you need some class or some instance that decides whether or not the delivery
28:22
should be for free, so I call this the delivery manager, and we just create this delivery manager, give him the customer and the basket, and ask him, should this delivery be free or not? And the third thing is just checking, validating the output. I state the delivery should be free,
28:40
so in PHP unit speak, this is assert true, this is free. As I say, well, this line could also be in the test because I think it's almost readable, right? Even for non-technical people, but if you write, then the delivery should be free, that's even more readable. So it's not, there's no magic behind it.
29:02
This is, if you're using Behead or Cucumber, this is what they do, right? They just match sentences to snippets of code, but you don't need a tool to do that because every programming language already knows how to match a sentence to a snippet of code, and it's called a method,
29:21
so I never had the need of using Behead for that. And yeah, and this is a specification by example. For me, how I define it, and how I've been using it a lot, and I've been using it for two years now, and for all my own projects, I always specify them this way, and it works really nicely.
29:42
I haven't done it too much with clients yet because it's still a lot of educational work you have to do with the clients because, well, yeah, you have to write these examples beforehand, and that means you have to start thinking about what you want to do before you do it, and a lot of people don't like thinking
30:02
about what they want to do. They just, they love just dumping everything on the programmers. They don't like thinking about what they actually want to do, but it totally pays off once you get there. So there's also a book with the title, Certification by Example. This is why I call it this way. It's a really nice book when it comes
30:22
to describing the terms, when it comes to, well, making up new terms mostly. It doesn't help with how to use it. It doesn't explain very well or at all how to implement it in your own project
30:41
or something like that, but it describes the whole process really nice, and it describes a lot of other teams who are using it and their experience with it, but it doesn't say how they use it exactly. So, oh yeah, this is the subtitle, or how you call it, the sub-caption here, is How Successful Teams Deliver the Right Software,
31:02
and I think this is a really nice sentence. No surprise, this is on the cover, because it's the hardest thing is usually to do the right software, not to, and I describe it like this. Okay, this is us again. This is the developer, poor guy, because he has to work with the machines.
31:22
They're really stupid, and we have to teach them something. That's terrible, but it gets even worse. We also have to talk to all the business guys who hate thinking about what they want to do. They usually don't know what they want. We have to figure it out, and then they change their minds all the time, so it's terrible. So, we have two main purposes.
31:40
We have, obviously, we're the one doing everything. We have to do the thing right. We have to create bug-free or error-free software, which is hard enough, but even harder sometimes, right thing, it says. Hard to read. We have to build the right thing, because if we, like the best error-free,
32:00
full-featured software is completely worthless if nobody wants it, if nobody needs it, and if it's just not the right thing. So, this is really hard to do, usually. It's hard to figure out what the right thing is for the business people, but some are really good. But then, we have to understand what they think the right thing is, right?
32:23
So, to make sure that we implement correctly, we use automated tests. This is a really nice way to make sure your software works as you intend, but that doesn't mean it works as this guy intends. So, what we do then is we write specification, usually.
32:40
Well, this is what we did in the 80s, right? The whole waterfall approach. We wrote pages and pages of specification that specified everything, and then we implemented it and threw away the specification, basically, because it was wrong anyways, and then we wrote pages and pages and pages of documentation, which we also had to throw away
33:00
every two years or something like that, because it was outdated. But using the executable approach, they just transform. You just write the specification, and then you implement them as tests, and then, documentations come out in the end. So, it helps you to do the right thing, not only the thing right, but the right thing.
33:23
And as I said, how I do it is I just write code for the specifications, because that's okay, because developers are still involved. So, as I said, I don't quite follow the approach of Cucumber, where you write text files, plain text files, with the scenarios
33:43
in a domain-specific language, and then that gets parsed, and then you have this huge tool that does nothing but parsing sentences, so code comes out of it. And this is completely unnecessary, because programming languages already are capable of describing these things.
34:00
And also, and I think Cucumber, or like Behat, they always say, well, but this way, the business stakeholders can write the scenarios themselves, right? But I've never seen that happening. I don't believe this will ever happen. Has anybody ever seen this happening, like a completely non-technical person writing a test scenario themselves?
34:20
No, me neither. So, also, they cannot do this, and they should not do this. The business stakeholders shouldn't write the scenarios, the specification themselves, and the developer shouldn't write the specification themselves, neither. This needs to be a collaborative process. This needs to be done together with as many people as possible,
34:42
with as many roles as possible. So, the analysts should be involved in writing the specification, the QA people should be involved in writing the specification, because everybody has his unique approach, his unique perspective on things. So, in order to write a good specification, we can only do it together.
35:01
So, why not do it in code? Because it's easy. But then, the documentation can be read by non-technical people themselves, and should be able to, because we're using a ubiquitous language, we're using a language everybody knows, so they shouldn't need a developer to find out how the system works.
35:21
And before, or in every project that we weren't employing executable documentation, I got at least, every day or every other day, the call asking, so how does the system work again? Like, can you please describe it to me? And of course, I didn't know anymore, because what do I know? What I did two weeks ago. So, I had to go through the code,
35:40
and read and reverse engineer how everything works, and then come back to whoever called me and describe it to them. And I hated doing that, because I hate reading code, and I hate reading my own code. So, I needed a way to avoid constantly having to look up again how things work.
36:01
And this is why I just gave those people access to the code that described the system. But that was not an ideal approach, because it was still hard for them to read it, it was hard for them to find it. They had to actually install Git on their computer,
36:20
and check out the repository, which was like several hundred thousand files, and then they had to, I was not ideal. So, what we did instead is we made an HTML output of this documentation, of this code. And it was very ad hoc, but it still worked nicely enough,
36:42
so it did nothing else but parse the files, and showed them quite nicely in HTML. But then after I talked about specification by example, last year at the FrostCon, we talked afterwards, and people were like, yeah, it's really nice having all this code,
37:00
but why not show it as HTML, and why not make a tool, an open source tool for it? And I thought, yeah, actually good idea, let's do it. So, I started doing it, and this year I actually have it, and I can talk about this. I think this is really nice. This is basically, did anybody see last year's, me last year? Okay, one, yeah, you obviously.
37:21
So, this is the, nice. So, this is the follow-up on it, okay? Maybe you remember it. I said, okay, yeah, I really wanna do a program that exports it as HTML, so people can read it on their own. And then once you have this, once you have this nice browser for source code,
37:41
everybody can read it, and you have a single source of truth, which is a very nice side product of executable documentation, because people stop discussing unnecessary stupid things, like how does the system work? A lot of times, if you ask three people,
38:01
how does this email work? When is it triggered, or what does it contain? You get three different answers, because nobody knows. Everybody thinks they know, but nobody does know. The only instance you have that is actually true is the code, usually, and that's only accessible to developers, and even, yeah, as I said, I didn't like writing it,
38:21
reading it. But if you have this documentation that you know is true, because it's self-validating, everybody can agree to it. And the second nice side effect is that you also, you unify the language, okay? So I don't know, we had one entity called topic, but it was also called keyword or post.
38:43
It had like five different names, but it was the same entity. And depending on if you asked a developer of this team or of this team or the marketing, you had like five different words for the same concept, for the same entity. That was very confusing a lot of times. And if you have the single source of truth,
39:01
if you have this executable documentation, people have to agree on one language, on one term for things, because it's code and it doesn't like ambiguity. Was it? No, well, double meanings, anyways.
39:20
So now, yeah, I think it's a good time to show it actually, to you how it looks like. Well, that's a little bit too far ahead. Just wanted to, first I wanted to show you, is this seeable? Yeah, what the hell? Okay, this is the documentation as it was of Mockster. So as you can see, I really put a lot of effort in it.
39:42
It has like color coding and everything. And what I did then is I, I wrote a test file called introduction test, where I put, and I have a lot of other tests.
40:01
So this is actually the specification of the whole library. It shows you how to create mock, how to filter functions, how the injection works, and you have this introduction test. And then what I do with it, I just parse it, I just read the files and show them
40:23
in a nicely readable way. So check return value test.php becomes just check return value. And also on the right side, you have these little green numbers, which indicate how many test cases are in this file and how many are passing or failing or incomplete.
40:42
So it's also integrated with the CI server that just sends, I'm using Travis CI, and at the end, I just have a cURL call that sends the report from PHP unit to docs, and then that is parsed and matched up
41:01
with the test cases. So it also gives you an overview of how the project stayed. Like if you have a lot of incomplete tests or which features are still incomplete, because you can think of each file as a description of one specific feature.
41:20
And then when you open the introduction test.php, is that readable? Yeah, right? It looks like this. You have here the public function test basic usage, so it needs to be called test because I didn't wanna change my PHP unit settings,
41:42
so it finds it still as a executable function. And then I create my bunch of class definitions that I need in order to work with it. So I define your class and I do this in an EVO, so I can do it again and again.
42:05
And then in the end, on here, I just create a mock factory, I get the mock, and as you can see, the comments are written in markdown, so they can contain any,
42:21
but they also can contain HTML and stuff, it's all displayed then. And this is how it looks like. So we have this introduction test, we have three methods that are displayed as three sections and they are also colored green because they're passing, if not, they would be red.
42:40
And then the markdown, the comments are passed as markdown and displayed as HTML. You can also do nice JavaScript things, so I hide the class definitions because they are huge and ugly and usually you can infer them from the code itself. So yeah, this looks almost exactly like the README
43:04
from GitHub, but it's actually executable so I know if it's wrong and it's also nicely browsable because you have all the classes on the left side and you can just, yeah, access functions like this.
43:21
And I also wanted to show other specifications, so this is the introduction test, it's kind of special because it has a lot of comments, it describes the system from the BERT perspective and it has a lot of comments,
43:40
I talk a lot about the system and it doesn't have that much code. But the other test cases or specifications have more code so they read, is that, maybe make it a little bit bigger. Where is the nice one? Well, let's do the first one. So here you just have the create mock test
44:03
and then I say, okay, given this class definition, when I create the mock, then it's property A should be B and so on, so I describe the system just in words even though I could, because it's a library, so I could just write the code and it would still be very readable and maybe even better readable
44:22
because you could just copy paste it as I did in the introduction test. But this way actually helps myself because I can read it better myself and also people foreign to the project who don't know the internals and don't want to know the internals can understand it.
44:41
And then this gets also parsed, of course, and it shows, it's displayed like that. And as you can see, at this point, I also parse the code and display it in a different way. I strip the this and I also turn the camel casing
45:02
into space sentences and I fill in the arguments which are usually in the end. So here it says then the property call should be false, so you don't have to do the underscore replacement in your head, which I think is a really nice thing too.
45:22
So you can do that too. You can parse your code in any way you want. If you use this for an API, for example, you can even have a specific field for the request and a specific field for the response. So they're also very easily understandable
45:40
or displayed in an easy to understand way. So you can do anything with it. And yeah, this is just way easier to read than the code, I think. So yeah, people usually like that better than the code. Everybody who is not programmer, definitely.
46:01
So any questions to that or anything you wanna see here? Well, I mean, it's public. You can just click around, edit yourself if you want. Okay, so that was just a really quick demo.
46:20
And how it's done. It's not much magic. I just take the PHP file, I parse it into a structured format containing the class or the methods, the content with markdown and everything. And then I just output it as HTML.
46:41
All of this is done on demand right now. So directly, I don't do any caching because I don't need to because, well, it's very static anyway and still fast enough. But of course, this could be heavily cached so then it would show instantly. Oh yeah, like in case anybody cares,
47:02
I'm using the PHP parser from Nikita. It's very nice, it has a little, it works very nicely and fast enough. And markdown parser, I use parse down from erusef, just where credit is due. So this is the pipeline.
47:22
Really easy. So just to recap, we're almost done here. Specification by example of behavior driven development is about communication between these two parties, between the developer, between the technical staff and the non-technical staff. This is a problem that a lot of companies have
47:41
that depending on the size and the culture to different extents, but I've seen this everywhere. That it's just really hard for these two people or two parties to communicate with each other and there are a lot of misunderstandings which leads to frustration, which leads to worse products. So it helps a lot to streamline the way people think about it
48:00
and they communicate about it. And we do this using examples because this is a format that is universally applicable and you can have examples in any level of detail. You can have very abstract, high level examples and you can describe very detail specific parts
48:22
of a system using examples, but it's always the same approach no matter on what abstraction level you are. So you can use this for unit tests as well as for integration tests. You can always have the same format which just makes it a lot easier to approach.
48:41
And examples are specification, our tests and our documentations at the same time. And you transform the specifications into automated tests using this method, specification by example, and then you can use docs to access the documentation itself.
49:01
But yeah, that's actually optional. You can just read the code as well. That already helps. Yeah, I think that's it, but not quite. There you go. As I said, I didn't talk too much about specification by example today, but if you are interested in it, then just read the book which I showed.
49:21
Yeah, this doesn't work anymore. Or check out what Dan North says about it because he came up with the term as far as I found out. And I think what he says is still very close to the original meaning and is not too much spoiled by the whole cucumber behead approach. And he also has a very good talk.
49:41
If you don't like reading too much, if you like watching talks, this is called How to Sell BDD to the Business. And it's a very good explanation how this, yeah, even for non-technical people. For example, if you wanna convince your boss,
50:00
then you can join this talk or just send it to me. And while I'm giving out goodies, everybody should read clean code. Who has not read clean code by Uncle Bob? Okay, do so. If you're programming, it's really, I read it every four years. It's just like you forget things.
50:21
And it's just, well, I forget things. And if you're into agile and stuff, you should definitely check out Extreme Programming which is like the father of agile and still in its purest form, I think. And also I can recommend The Lean Startup. It's a book about, yeah, stopping waste.
50:42
And I think the whole agile movement and this executable documentation is a very agile method as well because it's just, the idea is to stop waste. So to waste is, if you write a specification and then throw it away later, then you just wasted a lot of brain power and a lot of paper too or whatever.
51:00
So whenever we don't produce things we throw away later, whenever we have active artifacts that we can reuse, we have less waste and more fun with everything. Well, that was it. If you wanna check it out yourself, you can find it at docs.artans.org. You can find it on GitHub. You can fork it, whatever you want.
51:23
And you can find this presentation and well, lots of other things at artans.org as well. I'll upload it hopefully tomorrow or maybe even tonight. Then you can, if you wanna read the links again and stuff. So thank you very much.
51:43
If you want, I can do a really quick five minute demo. Of the tool that we've done. Okay, let's see how many questions we have. And then, are there any questions? Yes.
52:08
So the question is if I can show what the business would see. And this is what I showed here. And it depends very much on the domain and this is usually very readable to domain experts
52:22
because they know the words and they're into it. If you ever used a mocking library, then you understand what a class definition is and when I create a mock. But this is usually what I show to them.
52:46
Yeah, I don't. You mean the code that I implement?
53:00
Like this. So this is what the business users see. I don't show them the code. I don't show them how I implement it. I just show them the specification or I don't show it to them. And usually we come up together and create it together. So I don't just show it to them. If they're interested in the code,
53:21
if the code is themself, then I usually show this part but that's never the case, actually. Okay, yes.
53:41
Okay, so if I'm using this approach with other languages as not English or as Ruby. Yes, I've actually, I've done a coaching with a guy who didn't like English that much and I introduced him to specification by examples
54:00
and he preferred German so, but it was a little bit awkward. So we wrote. Angenommen es gibt eine klassen definition, wenn das Pacifiche, dan zuolte das Pacifiche. So there are equivalent keywords and you can just sort of translate it. But if you're referring to whether or not umlauts are presented correctly and parsed correctly,
54:21
I don't know actually, I haven't tried it out. But I mean that. You don't get that like it. Yeah, if you find that it not works, you can just patch it in. Okay. So where the difference between behavior-driven development and test-driven development? It's very similar.
54:42
The difference is that in test-driven development, you write automated tests in code that only programmers can read. Behavior-driven development, that's basically the only change. It has a lot of implications, that one change,
55:00
but that's the basic change, at least for me. I bet if you ask different people, they may maybe answer different things, but that's what the main difference is to me. Okay. Any questions else?