Jozi.JS 2018, 28 Jul 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Squeaky Clean Scripts with Maid - Luke Warren

Description

Writing well documented and maintainable scripts is hard! Complicated npm scripts fast become difficult to read and reason about. Due to this complexity, we end up writing separate documentation for our scripts. This documentation soon gets out of sync and stale and we instead of solving our problem we have added to it!

Using literate programming and a CLI tool called Maid, we can write our code inside of our documentation. We can then use our language to describe the code and determine how it is run.

This talk was recorded at the Jozi.JS meetup group on 16 August 2018.

https://www.meetup.com/Jozi-JS/events/252392124/

Disclaimer: The opinions in this talk are those of the individual and do not necessarily represent those of this channel, the meetup group, or it’s sponsors.

A

We'll see on location a with angular and JavaScript's around our functional code. You guys might remember me given talk before, but functional JavaScript with Ranbir. The Nemesis will run a really cool thing. It's like a new hotness was not really about using it. It's just basically already nectar scripts and basically, how many document things popping people down the line. I'm a stripper.

A

You get such a little bit on literate programming, but that's more just who you think I have a solution, so I had to make up the problem. This is not a serious problem.

A

The the product for us today it has not read long one-liner statements now, package JSON files like in the scripts, and sometimes they like to know what's going on so I, think you really want to make comic, dance or writes and documentation about it. But that doesn't happen. The next person that comes in he needs to read that it actually does know. What's going on, that's quite complicated future maintenance, the project have nope you and they need to convection.

A

Arsenio suits this sort of Department and they struggle this quite a lot because they're not like dogs to developers per se, but they get stuck in the Java project.

A

Things like this I guess like solution on one side. It is this is what to understand. I mean some of us: okay, you're writing dogs, and they got sits for a day or two right, the whole bunch of dogs, and they might be accurate. They might be eating food, but they might not be okay, they they're written as a octopus, so there might be pretty quick. Actually, it might be like the day minimum that you need at the end of the day when things changing the suppose.

A

So hitter on this, wouldn't because we had like living breathing documentation, documentation that you're working all the time. The code that you're talking about is roughly a negative thing: okay, documentation, that's radical.

A

That's that's: okay, literate programming, sort of fits in absolutely its intermingling of the code and your documentation in sort of one place, so the documentation, our and our case may be I build scripts and the scripts are the documentation there. One thing they live together: they change together, they don't become stale, one doesn't come still.

A

So next mission is not collective, we're writing a documentation. What are you gonna write it in.

A

The obvious one that is most honest to the sector, but you do not give up any pointers where to see Montgomery Microsoft or they don't saw in on get up Amaka. So company not get to talk to you.

A

If you haven't looked in Lockleys anyone not to the mob family. Before who said it's, it's a really just simple water, we'll be able to write documentation system. So, if you want to add something, that's you just wrecked starter on. If you wanted something to be hitting, you just have a hash of photos and.

A

So mark on really has supportable code blocks inside of it, but we just need the ability to run those programs. You might see in like examples that you really don't know. This is how you do it and here's the code example- and this is we made skips in so maybe that you like super duper simple. It's just like it's an online tool that allows you to run the okay, so your actual scripts inside your dots and then you use English to describe how your code is going to run.

A

Okay, how your one script interacts with the other.

A

That sounds great, but that's. It sounds weird and hard. Maybe something to do it. It's actually not do not mock down you really, not good, then your next show and it actually comes out to choose really simple things. The first thing is your script name, which is H, that's what that's, what you use to run, run and you'll produce voice inside of a typical back tips. If you know about Excel the Machine off so after the Thompson scary.

A

Demos even go wall.

A

Because you see underneath job just got a demo directory, I've got a made farming made father indeed mark on farm and on the right. This is the demo one and we can see. We've got two 6740 section and we were a Lansing station and we've got seven just explanations: it's all documentation, you do a preview, but it's not so pretty. You could put a bad share and get some.

A

So you could put that there, but now my code is yeah and I've commented out, but I've got living code. Action we'll see how that goes. So the first thing you need is you're. Gonna need me, so you gonna use made like this. If you don't have it obviously you're just going to npm install you can sort of globally, you can store made like that. You can destroy, it ever be able to instantly right.

A

Now we get in extreme a producer. The first thing we do is to say: okay may help me. Okay,.

A

Good so much okay, cool like well. This is all what we know how to do. We know how to taste it and taste runs of the parties and let's make sure that the code follows pretty dimensions: okay, so cool! This is like a manage, but now so it's taste really super simple, so you can see an opportunity, solid tips. We ran our really thorough tests and- and we can see our hundred-percent.

A

Opportunity on the grand picture, okay and so many you could, let's talk.

A

Okay, but this is like this- is super basic or you could just use. You know just a scripting engine part. That's not the point. It's just straight out the basics part of it. So in our second demo, we've got a little bit further. So again you put those same sort of come on your buck. Teeth and you've got and got a foot box, but now in our team, your doctor on our Linton before kids, okay, so this is something that you should put inside a reward.

A

You know your scripts, but why not just document actually make that explicit, so you made, if you say, okay well, lends them in it lends impetus whatever we're gonna, say: okay. Well, let's taste come on also runs the palace before it.

A

A

They say may automatically to see their to starting minting, say, there's an angular and then it's going to completely so it ran the taste-off to the benzene. So these are things that are in our documentation, we're using the English language to the spend. However, power Africa are powerful, scripts interact and work together. We're not relying on trouble knowledge to know or are they today run this one runs after that, one and so on. It's actually it's document and if you look at our preview again, stop pretty bad.

A

Okay still, the fact it's my facing this, the before keyword and surrounding the back texture, okay, so runs tasks before after the same.

A

A

So we'll get a little bit a little bit more fancy.

A

So now they're doing you've got someone's foster in it. Like super basic, it's just in your mind. Okay, look you just missed or anything for our clients and we store anything to our server. Okay, I'm gonna get a time. Okay, you just rip those together for one thing to happen together, so we've got a install c'mon and that's it's okay! Well, it installs alter the penalties but client and the server and it runs past install times and it's full server in parallel. Okay, so if I ran.

A

So far around the store see I'm starting them together parallel and it's go run, my own store like that, which is cool. That's it easy, and some of you find some acne need something together. So I've got to stop and start server, yeah I'm going to start up to give it in parallel thanks for asking a lot, and it explains exactly what splinter is they made hello?

A

We're on man page explains exactly what you do you get this project you've never seen it before, like I'm a so silly, hey look! What's going, how do I do this? That's how you do it, but that read the docs and ran the box. So it's a pretty cool thing. So if we stop things out.

A

So it started at God and then angry we'll take two hours.

A

And you can have a script or sometimes you just want to stop it. Sir.

A

You can do that too.

A

So it's pretty simple, but although once they further, it's a usually what happens? Is you get? This point like this is really cool and it's really handy, but I've really got to really fun. I, don't want to make fun I, don't I, don't need extra markup I just want my being a my own okay! Well, you can really easily do that.

A

So now we're going to really fall. You see that are they staying Tapia, okay, so I, don't approaches. I leave me like hey cool, like we've got a cool readme file. It show up yeah awesome, so he let some types of scripts in here which you've got to ensure that's really pointless. Video did you get the idea and then we have a script secret. So all you need to do is.

A

So we need to do to Tom made now. Okay, I just need Tony like where my scripts are in my markup on you just stick. This comment, yeah they taught, and then many other difference is that, instead of the h2, but to hash hash tags, it's going to be so again. If you say man, huh okay, we have the exact same touch than the previous one, because I just got them facing them, but we're it's all the same. Okay, so you can actually start removing this in into your evening. You start using it.

A

It is it's not real life.

A

So that the next thing you like, maybe you are you might not like so just use JavaScript, you can do that. So, if you just say okay well, this PO Boxes JS, you can huggabug things you can even use like async/await gets a bit funky now.

A

You can also require things yeah, so you could use over. All I can do like. Maybe you hate yourself or something you could use passes.

A

And then I throw it in there if you want to use it as their so you've got a few options. Typically.

A

So sort of in closing, if you're on Windows, you know media you skip that to run or windows subsystem forward. X.

A

And you can use your Ruby file as a saw, and you can pass arguments to your talks like that. You make easy to do sort of good Doc's. You'll, see that it's really easy to do just depends on what language rewriting the script yeah. That's it cool any questions.