Programming Throwdown - Code Documentation

Episode Date: April 4, 2018

Writing documentation is an art and there aren't many cut-and-dry rules that will guarantee the right documentation quality. In this episode Patrick and I chat about our lessons learned and also cover a bunch of ways to document and write self-documenting code. Show Notes: http://www.programmingthrowdown.com/2018/04/episode-76-code-documentation.html ★ Support this podcast on Patreon ★

programming throwdown episode 76 code documentation take it away patrick i'm so excited to be doing another full episode again or i guess they're all episodes, but a non-interview episode. I'm trying to get a bunch of topics off of the chest. That's true. Yeah, we should. There's definitely some interviews that are kind of in the pipeline. There's nothing immediate. But yeah, we definitely are really getting caught up on a lot of a lot of our like focused episodes i guess so

to speak or non-interview episodes and yeah if people have suggestions now's a good time to hit us up because um you probably won't have an interview next month either so but also i feel like people might groan a little and be like code documentation really you guys are scraping the bottom of the barrel but jason suggested this and i thought about i actually think like i don't know i'm kind of excited to talk we'll see how it turns out but yeah i mean this is one of the most important things because other things you know uh if we talk about specific languages maybe you're never going to use that language ever but this affects everybody and hopefully uh yeah and i think it affects it affects everyone who's programming pretty profoundly, a lot more than you think.

It's one of these sort of, like you don't really imagine other people reading your code. Like even just thinking about it, it's kind of weird. Just thinking about somebody else, just like trying to figure out what your code is doing. But that happens all the time. And so even though we might not think about it um and so documentation um i feel like we have a really a lot of good things to say about it so so the first thing i want to talk about is uh system design questions on an interview and i'll do a little like what that means and why and then i'll let you go first jason but um the to me if you're doing an interview and lots of

people you know listen are either looking to get a job in computer programming or graduating college and looking to get a job or um even just i think i actually think it's good to interview every so often just so you sort of get practice with it even though i don't always do it as much as i as as much as i should and it is a lot of work but it is one of those things I think being prepared to interview is always sort of good. And a system design question is instead of the expectation,

at least at many tech companies, if you interview for a programming job that you have to do coding on the whiteboard, the infamous whiteboard, or even just on a computer or something. System design is saying, hey, let's move

this up a level from writing a program that you can do in 30, 45 minutes to talking about how you would design something. And still maybe in 30, 45 minutes, sometimes some companies will do it a little bit longer for this question, but it's sort of a higher level question with more moving parts and often doesn't involve writing code. Yep, totally makes sense. So we were talking about this a little bit before the show, but I do machine learning, as probably a lot of people know if you listened to our machine learning episodes.

But we actually have a separate system design that's focused on machine learning that deals a lot more with statistics, like how do you sort of design it to be a little bit robust how do you collect the right statistics things like that and um yeah as patrick said you don't you're not really expected to write a lot of code you might whiteboard some diagrams and things like that um but it's really about how you tackle things at a high level and what most of the time we're looking for like what i'm looking for is and it depends on the levels of experience too but i'm looking for people who've kind of made kind of mistakes in

the past and are already kind of preemptively you know trying to design the system with those in mind or you know people who start off trying to figure out the limitations and the scope of the problem and things like that. And sort of making sure they don't over-design, under-design, and things like that. And we'll talk about that in a little bit more detail. So it's probably pretty similar to a system design interview, just with a different topic. Yeah, so maybe an example for me, you know, working at a company that has, or I guess any tech company that has a large internet presence, you know, you would expect to get a question that has something to do with distributed systems. So an example of that might be, you know, if you take an e-commerce site or whatever.

I hate naming names because I don't actually, you know, particularly want to, I don't know anything about the details, but if you just say it as an example, like Amazon or something. So Amazon has, you know, people are familiar with kind of the UI. So, oh, it has a product page and on a product page, you know, you go there and it might want to say how many people bought this product in the last day. They don't do that, but maybe they want to. Maybe they want to add a feature. When you visit a web page for this particular kind of salt shaker, this salt shaker was sold 10,000 times yesterday. And they think that'll give you, what did they call that?

The social benefit of seeing that other people are making this decision as well. And so they'll ask you, how do you design that? And so they're really, it's open-ended. There's lots of ways you can take this. So the first thing is to make sure you kind of understand the kinds of things they're interested in hearing from you. If you're a web designer,

maybe they're looking for how you would figure out where on the page to put it or how to style it. If you, you know, are interviewing for an infrastructure job, you might start thinking about, okay, this is Amazon. They get a lot of people coming to the website. When it says yesterday, 10,000 people bought that, Is that yesterday in the trailing 24 hours? And then how fresh does that need to be? Or is it in a bucketed, the last, you know, sort of midnight to midnight day? And how do we compute that? How do you collect it?

How would you produce it? Where would you store it? So Amazon has, I don't know how many products, millions of products, and all of them need this value. Is it something you would compute when a person loads up the web page? Or is it something that you would pre-compute, you know, on sort of a rolling basis and store in a database somewhere? And if that database, does that database need to be sharded? What would the query look like? Sorry, I'm actually not

giving answers. They're just giving more questions. questions but um you know these are the kind of directions you would start trying to take it in and the person you know depending on the interview the person may give you more details or they may not they may say you know oh yeah actually what what we have is you know we have a in a sql database and we'd like you to write a SQL query to figure it out. Okay, well, that's not really, I guess, system design. So that's a bad example. But they might say, okay, yeah, so it turns out Amazon has a billion products. How would you compute this value for a billion products?

And it should be computed instantaneously because we don't want to compute it for not popular products. Yeah, exactly. That's a big part of it is if someone says, oh, you know, I want to like compute it for every product. Well, you say, well, look, there's so much churn. We have our inventory is, you know, a gazillion products, a lot of which are maybe even discontinued or they're technically there, but no one looks at them and that, you know, we don't even have enough resources. And even if we did, it'd be a huge waste. And then you have to see like, okay,

is the candidate going to adapt to that and say, you know, Oh, that's a good point. I didn't think about that. Let's keep some kind of cash. So, and, and, you know, have a right through cash or is that the term anyways, have some kind of cash where, you know, when you hit the cache or is that the term? Anyways, have some kind of cache where, you know, when you hit the product the first time of that day, you have to do some computation and maybe you put a filler number there or empty or something, but you're computing it. And so then when the next person goes, et cetera, et cetera, if someone just says, well, that's the thing I thought of and I'm sticking to it, even though it's wrong, that's probably not a good answer.

So one thing in general is to be very adaptable especially in the system design interview yeah I think that's right I mean I think it's okay to not know something but as Jason pointed out to just like stick to your guns and if someone says you know oh I need it computed in the rolling 24 average hour the rolling 24 hour window uh and i you know you know computed to the last second or something you can't be like well that seems dumb uh i think we should just compute it each night at midnight we'll run a giant batch job and compute it for everything uh that would not be a good yeah i mean i have seen people try to do that or try to force it into their comfort zone um but in reality you really want to make sure you're answering the question the person's asking

yeah that's a that's the thing that's true in general but especially for design interviews is the interviewer has a certain path that they a journey if you will that they want to take you on and and if you deviate from that journey you know it can really impact your you know ability to kind of pass the interview right so so if someone says oh and i've done this before i've been on the receiving end of this where someone really wanted me to use uh like a distributed processing system like MapReduce. And they said, well, you know, you have to sort these numbers. And then I just, I was like, oh, you can get a machine. Now they have machines with two terabytes of RAM or whatever it was at the time.

I was like, so you could do it. You could just hold down one machine. And he's like, what if it only had a gig of RAM? And I was like, okay, well, you could have files and then you could still do it on one machine. And the reality is a person wanted me to go into distributed computation, right? At some point I figured it out, but try to read the cues from the interviewer

because they're going to want to sort of steer in a certain direction where they're going to have a lot of follow-up questions and things like that. But the one thing that I, know for i guess i don't know at least the background i came from uh not working a lot with sort of databases and internet services is the whole comfortableness with the aspects of database that aren't what I would have traditionally considered like writing SQL queries. I mean, writing SQL queries are important and I've espoused their value in, in everyday

programming. But I mean, I think that also just understanding the kinds of trade-offs that at a big tech company, or I don't keep, I keep saying tech company, I guess a big cloud computer company or internet company. I don't know people who have a lot of large web presence. Um, there normally isn't only one kind of database. There are actually many kinds of databases. And this is something that I didn't realize and is important to a lot of distributed processing questions. So as Jason mentioned, like map reduces distributed computation well if you're going to run distributed computation inevitably you want to store it um and so how to have data that can be accessed by big map reduce processes and stored from large map reduce processes things for

streaming data things that need to be strongly consistent versus eventually consistent. What does eventually consistent even mean? You know, how do you, you know, like load balance queries? What parts of the system should be stateful versus stateless? Yeah, so I guess like, so if you want to prepare for one of these interviews, one big thing is, is, you know, look at what the company does, right? Because it's almost certainly going to,

you know, revolve around that. Think about like, what are the biggest technical challenges at company X before you interview? Like if you're interviewing at, I'm just making stuff up like companies up, but if you're interviewing at Google, you know,

to work on their search algorithm then yeah you're probably going to need to deal with handling a lot of data and looking for things in the data and things like that if you interview at uh maybe like tesla to design you know a sensor on a car or something it's going to be a very different system design and so most people are going to ask questions that directly relate. I know when I do the ML design interviews, one of the questions is literally, here's a piece of our company.

How would you start it over if we had to start over from scratch? And that's basically going to be the essence of almost any system. There's definitely some generic system design questions um but even then they're going to revolve around whatever technology or whatever problems you know that company's solving yeah that's really good advice and if if i had to give i don't know unlike other things that it's something you can just go to you know a programming competition

website and do some example problems this one's a little different i think it involves more reading thinking like jason pointed out a great starting point is what the company does but i mean i think for me the big thing that probably helps in a broad stroke fashion is understanding the kinds of databases currently used and what the differences are and not like the difference between, uh, my SQL and Postgres, like those are probably two kinds. They're, they're the same kind of database. They're just two implementations of a similar kind. Um, but what's the difference between like Cassandra, which is eventually consistent and my SQL and why would you use one over the other? So that's like one area of research. Also, how data is indexed. So Jason mentioned like Google search. So understanding what a reverse index is and how would you do web crawling? When you do web crawling, how would you store the data in a way that's useful for doing search? How do you do string matching on, you know,

someone enters the, starts entering a word into google search and it tries to guess what you're going to search um and then how does it match that when you misspell something like how would that work how would you do that for very large data sets and do it really fast um those kind of general topics i think cover i don't know i want to say cover everything or most but i don't know of a great set of recommendations that would cover more yeah i mean in general you know almost every um company you know has i guess it depends on yeah i would say almost every company has some kind of front end like maybe um you're plugging into some existing system, like you're writing a plugin for Salesforce.

And so you're, you know, you're writing Salesforce, you know, you're writing some schema that's going to be rendered in Salesforce, right? Or some other app. Maybe you're building your own app, like, you know, mobile app. Maybe it's a website. Maybe it's all of those things, right? And so it's good to know like that company what is their interface their human interface right and and then think about all the way on the other side what sort of information do they need to store and then how can you sort of connect those two pieces like it's a

good way to think about it so it's a sort of and it's candles if you're a top down or bottom up kind of thinking person you can you can approach it from either end but yeah just think you have these that's the two ends of the universe and so you have to design kind of everything in between right yep um yeah so ml ml system design is is pretty similar i mean we'll ask things like, you know, for example, Amazon has the related products. So when you go to a product that says, oh, you know, maybe customers also viewed this

or related to this item, you know, how would you sort of design that efficiently? Or if someone goes to the homepage and you get some recommendations quickly, but Amazon has a catalog of, you know, a zillion items. So how can you choose the three most relevant items in a quick fashion and things like that?

So it's kind of similar. It just has a bit more of a statistics, maybe like a stochastic bent to it in a sense that if you go to Google and you type cat, you definitely need to see a cat, right? And maybe out of the Wikipedia page for cat, I don't actually know what comes up first. But in this case, you know, you could be wrong some portion of the time. If you don't recommend the best thing, you know, Amazon's not going to crash and burn.

But just on average, you want to be doing better and better. And so it's a little bit different for that reason. But actually, there's a lot of similarities too interestingly cat gives me the stock ticker on yahoo finance for caterpillar company but at the knowledge graph card on the right for cat animal oh okay and then has a link to wikipedia or something yes yeah second result is wikipedia oh there you go cool so on to on to news unless you have anything else no you were dying to know what my now i'm gonna do dog hang on no i'm just kidding are they are they equal are google employees engineers cat people or dog people let's find out i'm just let's move on all right uh, my first news story is kind of related.

It's, um, how to crush an interview. Um, this is really, really, really good advice. If you're, if you ever plan on interviewing again, which hopefully is a lot of people, unless you're retired, um, uh, you should definitely, definitely check out this video. Um, you know, the thing is in our case, a lot of our interviews that we give or that we attend are very technical, right? We want to hire people and people want to hire us to do XYZ. And it's very hard to know the person's competency over the phone. So a lot of this advice, he even starts off, this gentleman starts off by saying, if you're at the onsite interview, you know, they have your resume, they already want to hire you. This is how to make sure they like you. And that's, you know,

at least in tech, that's not true. There's a lot of people who we don't know if we want to hire them when they come on site, but still, uh, a lot of the advice is like really, really relevant. Just to kind of like summarize it quickly. And I'll add my own flavor here a little bit because because even though I watch it today, I was kind of busy. You know, I was giving it full attention. But but, you know, definitely be positive, be energetic, be kind of open to communication. Also, you mentioned you have a few stories, which I thought was like profoundly useful. So, you know, he said, you know, beforehand, come up with a few life stories that are relevant to whatever job you want. I mean, even if it's not,

you know, specific to a specific company, but let's say you want to be a banker. Well, maybe you ran, and I think the example he gives, you ran a lemonade stand and you collected money really manage the stand very well and and when people were working other than you they didn't know what was going on and the stand collapsed or something right um but he's like you know kind of have that good narrative and um you know have kind of good stories that you know revolve around why it's almost like you're kind of destined to be doing this type of job. And I'm kind of paraphrasing here. Definitely check out the video. That was just one of the tips.

But yeah, I thought it was really, really interesting. It's stuff that I've always believed, but I couldn't really kind of articulate it this well and kind of turn it into this sort of like uh a very concise you know set of points and uh yeah i definitely would check it out if you're ever going to interview getting off of interviewing from the first uh large well did you look up dog yet what's dog no i didn't here i'll do it right now okay fascinating podcasting um avoid else return early this was uh circulating earlier today actually but it it kicked off something in my Okay. Fascinating podcasting. Avoid else return early. This was circulating earlier today, actually, but it kicked off something in my mind,

so I thought it was good to talk about now. This is an article, a blog, about how from a coding style that a lot of people do this notion of only having one return function or one return statement at sort of the bottom of the function and having big if-else statements for handling everything and then returning at the bottom. And they were saying, you know, that they used to do this, but they basically have ditched it. And now what they do instead is, you know, if they check something and there's a problem, they'll just return early. And if they go down somewhere else and it makes sense to return they'll return in the middle and then you just return wherever it makes sense instead of sort of having these awkward if what they were sort of saying these awkward if else um and the

reading a lot of commentary on sort of reddit and hacker news about this people a lot of other people were saying you know that they also had been taught this and then i was realizing you know i was taught this as well like that you really want to only have a return statement at the bottom that this leads to the most readable code that the early return statements are problems and i actually thought about it for a while and tried to figure out what was going on here um and there were some comments this effect and what i realized is that i think if you're doing a sort of language like C and doing memory allocations and you return early or if you're doing multi-threaded programming and you have a lock and you have many return statements you need to make sure memory doesn't

link you need to make sure your deallocations are done your destructions are done or that your locks are unlocked and if you return early auditing the code and saying that i know every code path frees its uh whatever resources it's acquired um that that's tougher to do with multiple return statements and so i think that it has more to do with that but then realizing c++ with you know raii resource acquisition is initialization um in other languages uh having you know sort of scoped locks and these kind of things make a lot of this sort of go away that as you return that the instances and the variables in this locking you do you have more constructs which allow you to do these returns from various places safer and i think that for some reason that it just sort of never caught up that there's still this weird lingering paradigm being taught in school or

whatever i guess that you should have this return statement at the bottom and that it's somehow more readable when in reality it was probably more readable given if you have to audit for this other stuff. But now that you don't have to, it doesn't. So there wasn't a lot of rebuttal saying, oh, no. Yeah, I agree 100%. Yeah, I think it's like anytime you can avoid having, you know, like, what's it called? Like having nested brackets. It's always a win, right?

Yeah. But I was thinking just the other day, though, like I was in a conundrum like this. Like, oh, man, I have an awkward set of returns early here. I really need to refactor this to get all the returns down to the bottom. And then thinking about it today, like, yeah, I'm actually not sure that I do find that code with the more nested brackets more

readable and in fact sometimes it's difficult to know if you've kind of if else your way out of something for a long time like follow tracing that logic through the code is not easier than just like doing it and returning it yeah i mean my background is very different right obviously like i haven't done embedded things. Other than now, I have this robot project. And so from my background, it's more like if you have a recurrence or some kind of recursive equation or any type of induction, you say your base case.

Am I at my base case? Then just return. So in other words, if i'm doing some kind of uh fibidachi sequence or something it's like okay am i at the end of the sequence okay just return zero and then it's like okay i'm not at the base case then do some recursion and return that and so it's like yeah i mean if you're doing any type of dynamic programming type stuff or recursive or a lot of ai stuff it stuff like you're always thinking in that mode where it's like you have some base case you're just bailing early otherwise you're going

to do some other stuff and so yeah when i see like that type of code um yeah i mean it looks so much better with you know all the returns up front you know clearing out all the cases that you're interested in so i i mean maybe there is some good counter arguments for having the nested if else and in some cases if you do need to audit the code in in the way mentioned and there's no other way of like having better constructs that's probably reasonable but yeah i guess i i'm currently feeling like maybe i should abandon the vestiges of like having a single return statement at the bottom. Like, yeah, I mean, I'm not sure what the reason to cling to it is.

Yeah, I get I don't know too much about low level, but like I feel like creating an object, it can't possibly use that much memory, like creating a empty class or something. Right. And so you can almost always use scopes to do whatever you need to do there. Well, I've got a story about work I was doing all day today about the minutia of optimization I was getting into that would make your skin crawl then. Okay, probably. Oh, man. So, yeah, so my second story is, it's just a cute little infographic. It's called Idea Instructions. And basically someone took the visual style and the nonverbal style of IKEA instructions.

If you've ever built a chair or a table or a bed or anything out of IKEA, you know that there's, you know, in the very first kind of page of the instructions they kind of show you like these are all the parts uh and this is what you want at the end and they kind of walk you step by step but every step is meant to just like show some kind of movement but there's no uh uh you know words at all no labels if anything there might be like just very minute like at the top they might have two different types of screws and so the very first page might say look this is screw you know 900 and this is screw 901 and then later on it might refer to those numbers but other than that there's almost no text it's all just a bunch of pictures and someone kind of took that sort of style and really treated it like an art style and just a bunch of pictures and someone kind of took that sort of style and

really treated it like an art style and explained a bunch of computer science algorithms um like quicksword and things like that and it's it's pretty cute it'd be a good thing to print out and put like or get laminate not laminated but uh um like just put it on your desk as like a cute thing get it framed or something you do I wouldn't say you could learn them this way though I did try to follow a couple and for algorithms I knew I was like oh okay yeah I see what it's doing here but for algorithms I didn't I was like I'm not sure I followed this yeah I know no even like I'm looking at quicksort and like yeah I could kind of get what they're saying but yeah this has to be for people who already know what they're doing and it's just a cute thing yeah don't don't use this to learn anything so i we're gonna go for two youtube videos i think this is

definitely a record for our link section nice um but this was sort of something I've that I'd seen a number of before. But this one was particularly good. It's something I've always been interested in in cryptography. And that is the name of the video is Dealing Cards with Cryptography with Ron Rivest of the RSA encryption algorithm. And it's on the Numberphile channel. If you've never watched this most people probably have it's a super popular channel but um number file has got like math videos where mathematicians or other people explain stuff simply and it's got its own style and it's nice

easy watching um but this one has this famous cryptographer guy basically talking about how would you play a game of poker in the mail using the principles of cryptography and so he points out like well you know if jason and patrick want to play poker you know patrick has the cards patrick can't just shuffle the cards deal five for jason and deal five for himself because there's too much incentive for him to cheat i would just give oh yeah jason you totally all you got was three high terrible hand actually that would actually be good i only can get three high and not have got pairs i'm not a very good poker player seven high yeah right okay right all right okay good seven high yeah if it's uh what is it uh texas hold'em right uh i mean i think just like he i think his example is just whatever five card i'm not a poker person i think

just normal five card poker but basically like how does jason trust that i'm gonna you know shuffle the cards fair that we can compare fairly and it turns out yeah he wouldn't be able to do normally but if you use some of the things that are used for cryptography, and he actually sort of takes cards, puts them in envelopes, and places actual physical locks on the envelopes. And it's just really like I was watching it, and I don't know, maybe later I'll be like, why did I pick that for the show?

But I was watching it. It was just hilarious because this is something I've always heard described but i've never seen someone take actual physical locks put them on envelopes and and sort of explain the algorithm that's awesome and of course he points out this is how computers do it they do it really fast they do it all the time this is in a way kind of how public key cryptography is done uh it's just done really fast and without real locks um but if you're curious about cryptography or just want to i i thought i found it humorous uh you can watch this uh ron rivest on um numberphile doing dealing cards with cryptography i think he has a number now i'm trying to remember i believe he's done other episodes on numberphile as well he's not the host

um but he i think has made guest appearances on there several times um talking about other kinds of math and um he and explains in the video as well one of the ways that public key cryptography is done which is exponentiation modulo a factor without going in super details but if you've if you don't know anything about that uh then i would encourage you to to check it out cool yeah i will definitely watch this video right yes this show is done yeah well text me and tell me if i am like should delete this portion of the show and this is totally just that i had a weird quirk in finding it no this this sounds amazing this sounds really really fun it's not it's not a super long video and it is not going to teach you to get a job in cryptography so all right it might teach you not

to get a job book of the show book of the show my book of the show is hillbilly elegy which is um a really interesting book it was a bestseller um i just happened to be crawling the bestseller list and i thought this is something that is totally outside of you know what i would usually read and so i gave it a shot and i thought it was great um uh it's basically it's one of these things where like the the environment so it's a it's a non-fiction book it's about a real family so it's it's anecdotal um um and yeah the environment kind of is the book so without really spoiling anything let's just say like um uh basically okay after you know there's this there's this big industrial age there's there

was a lot of uh manufacturing jobs right? People working in like seal plants, things like that. A lot of those jobs kind of went away. And this is somebody who I think he grew up. So I think this person is probably in their 40s, I want to say. And so they're coming kind of on the tail end of that, or maybe they're younger than that but anyways so they're coming on the tail end of when a lot of those manufacturing jobs really went away and and it basically decimated this town and uh it talks a lot about uh you know a variety of these towns in appalachia which is uh people aren't from the u.s or people are don't know it's it's like kentucky kind of tenn are don't know it's like Kentucky, kind of Tennessee, Pennsylvania area.

And just about kind of how they got decimated. Nobody really knows about them. They have a lot of pride as a people, but they're also like kind of suffering like immensely. And it really kind of talks about a lot of specific things like I I've driven through, you know, Kentucky and Tennessee and Pennsylvania, but never actually stopped in any of those states. And so I know very little about their culture. And so this was like a really interesting insight into that culture. And it really talks a lot about specifically like why some people in that area or maybe in the U.S.

or broadly are struggling. And there's a lot of reasons why people are struggling. But if you were to ask me for, let's say, even 10 of them, I probably wouldn't even give one from this book because I didn't really think about things in this way. So it really is interesting. I mean, it's not an uplifting book, although, you know, it ends on a high note with some people really sort of making the best out of their situation.

But it's it's a pretty heart wrenching book, but super, super interesting. A great story. It really kept me engaged. It's, you know, I kind of tend to, you know, one day I know start reading a book or continue reading a book another day i'll do something else this book i just blitz through it because it really captivated me and i think part of it was that it was so different from what i usually read um so yeah i would highly recommend it it's it's it's a bestseller so it's it's really high quality and uh yeah i think it's a fantastic book i read it on audible nice i'm listening to oathbringer which is the third book in the stormlight archives trilogy by brandon sanderson i think i've had the other two books on here before i would love i actually have read a couple

other books but i didn't really care for them. And I dislike giving like mediocre. I have done it a couple of times, but I'd rather talk about something I'm really enjoying. Yeah. Even if I have the choice. Right. Yeah. And so this one I'm nearly done with. So one of the things I want to point out is, first of all, this is the third book in a

trilogy. And I just looked it up because I'm listening to it. It's 55 hours. This book, this book, the third book in a trilogy and i just looked it up because i'm listening to it it's 55 hours this book this book uh the third book um the others are almost as big and so this is a massive amount of like commitment to get through all of these and i was reading so i was curious it says the hardcover is about 1200 pages long for if that helps you think about like how big 1248 and i was thinking another book i did read an actual book form was anathem that i thought was like a very big book by neil stevenson and that one's only 937 pages so i'm not saying that like it's amazing just

because it's really big but but it's taking me. I was shocked. It's actually taking me kind of a long time to get through it. Is that because it's our books on tape or audible books faster or slower than reading? I mean, I know it depends on the person, but like does an average person or you, for example, do you read? I read much faster than the audible narration. OK, even if it's because you know there's reading like skimming through something no no no like just my normal reading speed is okay quite a bit faster

i never really thought about it until now i mean i've never like raced i sure but i'm pretty sure even like i'm sure i could read slower if I wanted, but like even just reading at like an enjoyable pace for me, I'd be much faster. The thing for me, though, is finding time. I guess I'm just too distracted. But like finding time to sit down and actually read a book is tough. And so I tend to not get it in as long of periods versus it can take me 45 minutes or more to get home nearly every day uh and so that is a time when i can sit there and do my you know get quality time with a book yeah makes sense um and so for me uh you know even if i could read faster so like this is 55 hours it might only take you

i don't whatever i don't i don't know what the ratio would be because it depends on your speed maybe 20 hours yeah 20 or 30 hours but for me finding 20 or 30 hours to read this is just like i don't i don't currently have it scheduled in and so but i i enjoy the content a lot yeah and so but oathbringer i am like three hours left or something so oh wow i'm down at the finish line but i i i don't know that it's going to have an amazing ending or not, not quite at the end, end, end yet. But I've really enjoyed it so far. So you've talked to me about or talked to us in the past about, you know, world building versus kind of building story and things like that.

Where does this fall in that sort of axis? So, I mean, if you have that much time or you know pages to go over something um so this is interesting uh i think this definitely qualifies as world building so it's very much about people and about stories but also about a lot of kind of you learn a lot about the world these people are living in um and one of the books i read that was a collection of uh short stories this is not the one i was saying i didn't like although i actually i'm not a big fan of short stories i don't feel i can get into them but um a lot of branders brandon

sanderson's books take place in a sort of meta universe called the cosmere um anyways this is like super detailed i guess it doesn't matter but he has a bunch of books that sort of feel like you can just read them in isolation and they are in isolation except that it turns out they're all really in a bigger universe and there are like common traits about the bigger universe and so um there are sometimes eas eggs between the books, if you read between the books. And this collection of short stories has a lot more detail about sort of the behind the scenes inside baseball of, you know, kind of that thing. And so I think not only is he doing world building on like a per series basis, but he's also collectively building all of the worlds together into one universe that makes sense that sounds similar to like terry pratchett books right where

where you know there's a basically there's a there's a i guess an engine for lack of a better word with a set of rules and an environment there and all the books take place within the same engine um and so there are certain things that happen that seem kind of just serendipitous, but over time you start to understand how the engine works. And so then when you see that thing again, you're like, oh, even if it's in a different book, you kind of know what's really going on, and someone who that's their first book isn't getting it yet. So one of the examples of this is the number eight the number eight in terry pratchett books is uh you can't say it if you're a wizard

so you have to do seven plus one is is uh you know two to the third or something like that um if you say seven plus one is eight and you get kind of struck down i can't remember exactly what it is and so there are just times where that comes up and eventually you read the handful of times in the series of books where um that's relevant but uh um but then there's still um you know other times where it happens and it's just kind of part of another story and uh and it just kind of happens and and uh if you know that you're like oh wow that's so cool like it's funny that just happened that guy got you know obliterated by a lightning bolt because he's the number eight but if it doesn't happen it just seems like just some serendipitous thing like what the lightning bolt struck that guy

down okay let's go on to the next thing yeah so i i to conclude i mean oathbringer is a really good book i i'm gonna recommend it even though i'm not finished with it yet but a little hard to give i haven't shared anything actually about the book yet but um i i it's hard to when it's the third book in a series so go check it out on i guess amazon or goodreads or wherever and and sort of read if you're interested in the summary or the back of the book. But you'd have to go to a bookstore to find the back of the book. So not going to recommend that. Right.

And you could read that on Audible. And if you are if you're not an Audible member yet and you want to join, use our link that helps us out. You go to audibletrial.com slash programming throwdown all one word and if you are an audible member or or uh you want to support us in any other way you can go to our patreon um just an update on the patreon so i think we're set on the design um actually i'm going to print out tonight my printer actually broke but but yeah i got a i got a new printer yesterday and tonight i'm going to print out the uh uh you know all the thank you letters we're going to write we're going to stuff those in some envelopes along with um the emblem and uh we're going to start mailing those out hopefully uh you know

in a couple weeks yeah i also had laser cutter issues so i am lagging behind and getting all of the logos cut so but yeah it's gonna happen it will happen before the end of the year yeah yeah and uh you know every christmas we're gonna do this hopefully uh no you know we'll get it more stream well that we're not gonna do this we're half our hardware breaks but um you know every christmas we're going to do this giveaway you know i have had my printer break which sucked but uh overall you know it's been really fun just you know uh really i mean part of it's just looking up where people live like because you know we need your address to mail you at the emblem just seeing that we have people all

over the world who uh support the show is is really exciting um and being able to um you know make something and uh something kind of real and physical and send it off to the people who are listening is really cool and so we hope you all keep uh you know keep subscribing uh definitely tell us you can use the patreon chat which i which i follow you know i monitor whatever um tell us what you think once you get the envelope if you get it broken or something definitely let us know but in general we appreciate so much your support also if you're in russia where our podcast is banned not because of our podcast specifically but just our hosting provider is banned um if you're russian uh you can access the Patreon RSS which is super fast and works in Russia

so nice tool of the show my tool of the show it's actually two but they both do the same thing iFunny and 9Gag so these are apps one is iFunny kind of like iPad like the letter iFunny

but it works on Android and desktop and everything. The other one is 9, the number 9, gag. So 9-G-A-G. Both of these are just basically a feed of funny things. And you can kind of tailor it. It also kind of knows, based on your upvotes, it kind of sorts it accordingly.

You can also look up certain things. If there's a certain topic you want to follow. But it's just a list of really funny things. It's usually memes, usually like a picture with some text. It could be a video with a caption. But, you know, I'm one of these people, I really believe a lot in this idea that, especially when it comes to emotions, that we're all like much simpler than we would like to believe right and so if you just see something silly and laugh every day i think it actually will have a profound effect on your mood and even though it's it sounds like such

a forced thing um and i wouldn't go into it saying like oh i need my funny medicine today or anything like that right but i just in general it's good to have like systems in place that you know may improve your life and for me this is one of these things like i have these apps um they send a notification like roughly every day and so i can kind of you know tap notification logs me in i get to see some really funny stuff and if i see something really funny you know i'll share it so occasionally patrick and other people get kind of random memes they're kind of like you know where did this come from and there's no context at all it's just something funny i saw in one of these apps

um yeah and i think it's one of these things that really kind of um it'll let you sort of bond with other people too like especially like you might not have a reason to talk to aunt sue but you could always send aunt sue the video of that cat you know getting stuck to a ceiling fan or something like that now i'm gonna have to scroll through all of it no i'm just kidding so it's speaking of things that definitely don't waste your time um yeah right jason informed me i'm behind and i'm not hip like all the cool kids but uh i started playing pub g because it came to mobile uh ios and android and i've been playing on a tablet um so not only did jason tell me that i was behind

the times and that he's been playing this for like literally months um but then he proceeded to tell me that the reason i am so good is because it was actually full of terrible bots and that i wasn't actually beating people i was just beating crappy bots so i was really stoked and now i'm just really sad uh so i need to stop the podcast and go back to playing. You got up to where you were playing people, right? I believe so. At least I'm getting crappier. So PUBG is Player Unknown Battlegrounds.

And it came out for desktop initially. And a coworker, someone on my team, actually said, hey, you should buy this game and we'll play together and i said okay so so we played it and it's just really hard and also i'm just generally not very good at at um games where you have to kind of be accurate like i don't have a lot of dexterity and so um you know i think i looked at my ranking i know granted i don't play that much i play maybe two hours a week or something. But my ranking is, like, I'm in the 70th percentile.

And I probably, you know, probably 29% of accounts are inactive. So I'm not at all good at this game. So just for people who have never played, it's actually really cool. I was explaining it to my wife. And I mean, I'm light to the game. I had heard about it before, but I've never played it much. Or I never played it, never watched a video of it. But roughly, the idea is you and 99 other people get dropped onto an island.

And it's sort of kind of like a mix of various themes you've seen before. Hunger Games, some different kinds of movies. But your goal is to survive and be the last person surviving. It doesn't take terribly long. I don't know if the computer one is the same, but on tablet, it typically takes like 25, 30 minutes maybe. Yeah, that's about the same. And so what happens is after just a couple minutes of being on the island there's going to start being a circle and you have to be inside the circle or this like energy field will come crush you when you die so

basically there's an ever-closing circle that you need to stay inside of um that's compressing anyone who's staying alive down into a smaller and smaller area thereby in theory you know if there was lots of people the density would go up and they'd fight each other. But you can also collect, but you start off with nothing and you need to collect armor and weapons and ammunition and health packs. And you're running around scrambling, trying to find it. And if you come across someone, then you bad idea as opposed to other games where you know if you're playing unreal tournament or quake or one of these games you just run around shooting everything but this game you know is a lot about sound so if you shoot everyone's going to know where you are and people who are really good at the game might say oh you know if i hunt that person down i can take his

equipment so so not you know just letting someone run away is actually not a bad strategy right so you know running away uh knowing if you're outgunned knowing if you are going to draw someone's attention there are some vehicles you can drive around the vehicles you can hit people with your vehicles um sort of a free-for-all it i i've i've been enjoying it i don't know how long i'll stick with it because you know it's one of those things like for me it was kind of fun like goofing around and like you know doing reasonably well at um but i'm not sure i'll invest the time to sort of get amazing at it there seems to be lots of subtleties and exactly what weapons loadouts you tune for and how accurate you are and

it's also quite a bit stressful um how does the how does the shooting work on mobile i'm pretty sure it's similar it's just you use on-screen controls or whatever well because like for example when you have the sniper rifle you have to be extremely precise with the mouse to hit somebody i mean it has some amount of auto aiming on but i don't know to what extent so um i there you don't play between a computer and a mobile device so they're actually two different implementations of the game as far as i understand that makes sense right yeah you get a huge disadvantage if if you're on your phone and so or vice versa or if they have too good of auto aim then you'd be at a huge advantage oh right that's true yeah so um i'll have to try the mobile out i actually

downloaded it but i haven't played the mobile version yet everyone probably already knows it i recommend youtube channels that have like two million subscribers and currently most popular ios games yeah you're such a rebel way to go against the grain although you told me you you literally pitched a book as it's good it was on the best seller list yeah we're just shilling the whole episode is just just an hour of us jump the shark it was popular i mean you know pub g bestseller list documentation i mean what's more popular than these things yeah and now we're going to talk about documentation the most powerful popular thing ever um documentation so um you know the first thing is and this is really true of anything is is why document and maybe we should start every

language with why does this language exist we kind of do but um uh you know why document right i mean it slows you down um it you know if it's not done right you have to keep it up to date i've actually seen some pretty funny code uh we have this thing called clown town and it's just a group at work where people post just miss like like bad code and it's usually just things that have like gone south over time like rotted in a sense and there was one with someone posted and it said uh the comment said return one but i don't know why and then the next line was return zero it's like so yeah that can happen um and so you know the reason why you know we want to document and this i someone explained this to me at work you know it's about five years ago and it's just so profound it's just one of these things you don't

think about is um you know if you're at a company you're almost certainly going to have some type of code review um which means like you're going to read your code because you don't want to review just you know you don't want to embarrass yourself right so you're going to go through it and then the reviewer is going to go through it um and even if you only have one reviewer and no one ever looks at it again that's already twice as many people, if you count your second pass. It's already twice as many people that have read it than written it, right? And chances are it's going to be way more than that, right? You might send a code review to two people. There might be other people on your team who look at it, right?

Also, you might come back five years later. This has happened where you come back five years later and look at something you've written. And you're basically a different person at that point because you have zero context. You're probably using this code for a different reason. And so that's yet another, you know, context that has to get filled in, right? The other part of it is you want to document to sort of let people know the intent of your code and also the span, right?

So, I mean, we talked about the design interview at the beginning of the show, right? Maybe you have a function that sorts less than 100 numbers super quickly like it runs on some you know assembly code or something uh and it's just insanely fast but only sorts 100 numbers well like you need to let people know right and there are actually like um what's the term for this there are actually like programming language constructs where in the input you specify like what's expected to come in and what's expected to grow out of this function. I'm totally drawing a blank on the term for that.

But in general, most languages aren't like that. Like most languages, you know, you just say this takes an inch. You don't say this takes an inch of this to this range right um i think it's like contract yeah yeah but but you know we're not writing like that almost none of us and so the documentation is really what's going to let the person know like this is the kind of input i expect this is the kind of output i'm going to produce, right? Even just simple things like if you're in a language that has null pointers, that, like, can this be null?

Yeah, yeah, exactly. Yeah, as I expected. So, I mean, the first kind of comments talk about is sort of generic across every kind of language i guess but most at least as far as i know every language has uh is composed of source files and there's kind of and and i've had this debate back and forth with people over time like do you document large sort of uh descriptive comments at the top of a file or Or do you mostly focus on commenting, you know, sort of at the line or at the call site or at the function signature or wherever the applicable place is? Do you do both? I mean, ideally you would just document everything all the time. But, you know, it is tough sometimes because like jason was pointing out you want to document

this so when you lose the context you can come back to it but it's also hard because i think sometimes people comment the wrong things like people comment the obvious things right and not the subtle things but that's really tricky because when you're in it and the context is fresh in your head you the things you think you might need to comment are stuff that is probably easy to figure out later. And the stuff that you chose for some subtle reason, you may not think to put a comment on. But generally, I think it is good, especially for large pieces of functionality,

to have a bunch of comments up at the top that sort of says what the point of the file is, what the direction you're going in maybe some use cases and that's going to force you to organize your file system it's going to force you to organize your source files in some meaningful way yeah i mean i'm a big fan of like documentation at all levels if that makes sense like your organization of your code should be somewhat documentation like what files are in what folders for instance um to me or in what modules is like a form of documentation like have a logical layout so that if someone's like i wonder where this thing lives they have a reasonable chance of finding it on the first try i've been in code bases before where

things just are all over the place. They don't make sense or just one gigantic folder. I don't care for that as much because I feel like it's documentation in depth. That's what I'm going to say. Yes. Yeah. I think too, another part of it is it's a living system in a sense, because there's just constantly people modifying it. And usually when you see, for example, as Patrick mentioned, a directory with 200 source files in it, nobody really set out to say, I want this to be the one directory to rule them all.

What happened is someone started with one file and then two files and then 10 files, and nobody really stepped in and said, okay, I'm going to take a month to sort of break this up into 10 different directories or something. And so, you know, it's going to require like constant effort. And that gets back to the downside of commenting, which is, you know, you have to maintain that. But, you know, the upsides are well worth it. Yeah. I mean, I don't think anyone's going to

disagree. Some documentation is good, but finding the balance is, can be tricky. Cause I find sometimes you get really long comments that are, you end up skipping because it's just like, oh man, this person like this. Yes. I know you're just looping over all the things in the list. Yeah.

Yeah. I got it. Yeah, exactly. Yep. Um, so yeah, I think there's also ways to sort of self document.

Um, you know, I think, I think, as Patrick mentioned, you can do the document at the top of the file. You could do documents in the functions, documents within the code, things like that. And the nice thing about those is, and we'll talk about these later, is there's something called generators that will kind of basically create a manual of your source code automatically. But in addition to doing that, something else that's basically free and, you know, it'll save you from having errors in the future. So it's kind of a no-brainer is to basically write self-documenting code. And so example of this and we'll kind of trade off different examples is you know and they always talk about one of the biggest problems challenges in software engineering is naming things right and so it's kind of like a tongue-in-cheek thing to say but there's a lot of

truth to that I think you know picking variable names and function names um is super super important i've noticed over time especially now that i've gotten good with you know emacs emac key bindings in whatever editor i'm using i have pretty long variable names and i find that that really helps a lot. So, for example, the other day I had something where it was a data structure that was a list of models. And then each model was a list of examples. And then each example had a list of features. And so I had a variable called top, or I think it was like root or something like that. And then I was interested in the first model. So I create another variable that was called, you know, examples, underscore four, underscore model, underscore zero. And it was equal root, you know,

index zero. This is like a huge variable name, but it tells someone exactly, you know, what that data is representing. And if you're using something like JavaScript with ES6 or C++ or something where you could do const, that's even better, right? Because now that variable is only ever going to represent that thing and people know it. In my case, I'm doing Python, so I don't really have const. But kind of style and and doing that with functions as well really helps and it could probably save you from writing a line of documentation there i mean i think anytime you have variables and are able to use them like like jason was pointing out rather than just indexing in now obviously you could take it to an extreme but providing extra context for something breaking up stuff into different

function oh that's a lot of stuff breaking up things into different functions and saying hey i'm gonna put a function here not because i need to but because it makes it cleaner to read um and anytime you can limit the number of variables, any piece of code you have to sort of think about to be able to execute, that's also going to be an advantage. Although we just said to make new variables. Um, but I mean, the keeping variables that are related around are good, but if you have code that just sort of becomes really long and there's lots and lots of variables in play, that also becomes difficult to read. definitely i think you know one thing i do when i'm doing c++ coding um and tell me if you do this patrick is is uh i tend to put a lot

of extra braces like it's not the braces aren't connected to an if or a for or anything like that but it's like i have a set of and maybe these are things that really should be functions, but I have some variable that I know is just going to live for a few lines of this function. So I just put braces to let people know, look, this variable dies right away. And so don't expect it to be around the rest of the function. And that kind of helps people modularize it. I feel like there's a trade-off, like you could just have a lot of functions and let the, you know, let the function, you know,

define all the scope and all of that. But at some point that actually can get kind of hard to read because you end up with a lot of functions kind of scattered all over the place. And you have to be careful, like how you sort of order them and things like that so it's so it's pretty readable um so i've found that for particularly like for small things let's say like less than 10 lines um instead of making a function for that i'll just wrap the variables in braces so that you know c++ kind of destroys it which that's not really that useful per se but it's really just that people know that this variable has a very small, you know, context. I mean, I have seen that before.

I don't tend to do the exact pattern you're saying. I mean, there are certain cases with like standard locks or if I know, if I have an expensive allocation where I need to do exactly what you're saying. I think people could use the, I don't remember what that's called. The curly braces without if or for loop or whatever, just the empty empty sections or the sections. Yeah, I think it's just called a scope, but I don't know. OK, yeah. So like using scopes probably could use it to better effect.

But I mean, I think you also don't want to go overboard. Yeah, like it isn't a standard thing and you know so yeah but i mean i think all this stuff is to say that you try to be careful in what you name things and use the features of the language to your advantage and in trying to help it make it descriptive but we've also pointed out that types are a form of documentation, despite Jason also said that he was working in Python. Actually, hey, hey, hey, Python, I don't know if you know this, but we use Python 3 and we use types on everything. Oh, everything.

Yeah, so Python 3 has a typing. You can import typing and then say like you know actually you do from typing import you know dict and list and all those types right and uh and then we actually have a type checker i think it uses my pi but um but yeah i mean you know it's there's not like a uh uh what's the word like a mandate or something it's like oh you didn't put a type here you're fired but it's like uh you know if if someone writes a whole file for example with no types then they'll probably get some feedback like hey you know you should you should put types here nice that's good yeah yeah the types are super super important without types it's just a night

actually patrick and i at the time we worked at the same company and we wrote a bunch of Python without types and that was pretty rough. Jason wrote a bunch of, no, I'm just kidding. Yeah, you're right. I know a lot of people really like stuff without types. We can get into that. Let's save this for a different discussion.

Let's keep going. Sure. So generators. So the idea of a generator is writing comments or specially tagged comments in your code that then gets exported to a web's page or a pdf or a different form that sort of summarizes your code without containing your code itself yep and you've probably seen this if you've ever um seen like you can tell because it kind of not to not to start off by disparaging it but it kind of looks goofy because you know these these generators

they don't they have to design the way they look on based on anything that could come out of your code, right? And so if you've seen this weird sort of four-panel type website where you have all the Java namespaces in the top left panel, the classes in the bottom left, and then I guess it's three-panel. And then on the right, you have whatever class you're looking at at the moment. And you'll know it when you see it. It's like they all kind of look the same. Very few people actually change a default template for the default theme. But yeah, that's something that was auto-generated.

And so those people don't have to create that website or anything. They just run one of these generators and a website comes out. They just have to put it on a serving platform somewhere so i'm gonna start this off by saying i actually dislike code generators as a whole i tend to not use them and you talk about like the document generators or just code generators in general oh no i get yeah document generators okay yeah yeah like java docs if i'm writing java i never like i dislike going and reading java docs i don't find them valuable i i don't we have some pieces of code that have doxygen comments on them i never generate the doxygen and go look at it i don't

know you don't think other people do like other teams or whatever i don't i'm scared i'm a skeptic i'm waiting to be convinced i think they have their place and i think if if nothing else i mean i think they're really useful for sort of enforcing a style to comments like you should comment on what your return type is you should comment you know what that each fun each you know public function for example should have some comment on it that says what it does um but i'm not like the problem is a lot of times when you try to make them very rich they actually become less readable in the code and so i feel people end up in this dichotomy of either making the generated docs good and the code bad or the readableness and the code better and the docs bad that's a really interesting point like i'll give

you a specific example where i agree with you on that is the parameters so if you if you want to do you know the if you want to support sphinx in python which is one of the code generators in Python, if you put at param, whatever the parameter name is, so if you have a parameter name like number of places, you do at number of places, colon, or I think it's at param space number of places space, and then a description of what that parameter is. And if you do that, it looks really nice. The output of that, like after you run Sphinx and you look at the web pages generated, it's really nice and you can hover over the parameter

and it reads it to you in like a tool tip, right? But the actual documentation looks ugly. It gives you at signs randomly. And plus, people start explaining parameters that don't need to be explained yes it's like you know i i know what that parameter means you know yeah that's the thing for me is like not only does like the documentation become sort of a little difficult and especially when people start using hyperlinks and stuff and yeah i don't like it just becomes really messy so having a hyperlink in your code is okay but

then having it flagged out and tagged properly so that it gets you know looks good in the documentation just becomes very cumbersome but as jason pointed out a lot of times which is true of documentation just as a whole topic is like understanding some things don't always need to be documented and so something like you know i'm trying to think of a good example it's like one of the things here's an example let's let's say you have an array of you know model an array called models and they have a variable called number of models because you're doing this in c++ yeah sure yeah yeah and you really write a comment number of models is number of models yeah Yeah, exactly, yeah.

Or a function called getIndex, and it takes in a variable called i, and you say i is the index of which to get the, yeah, ugh. Yeah, and yeah, to Patrick's point, like, you know, when you use a generator, it really compels you to have to explain things that probably don't matter. And, you know, what that means is people will get a little bit more deaf to your comments. Because if half the comments don't matter, they're going to pay less attention to the other half. I guess I also have this worry that there's

a sort of a amount of time people will spend documenting and I want them to spend it on the stuff that matters most. And if they're spending it on, you know, cleaning up the formatting and spacing of every one of their parameter names that don't matter, they're not spending it in like restructuring the code in just a more readable, maintainable way. Yeah. On the flip side though, like if you look at really core libraries,

you know, they make tremendous use of this. And this is like, you know, library tremendous use of this and this is like you know library like tensorflow or for example like tensorflow there's so many people using it they're in a sense taking a risk because you know they're using tensorflow instead of building their own thing and if it turns out they need to extend tensorflow in some way they're really counting on there's like a social contract there and uh if you don't have the generator it's it's kind of hard for people to get started you know just diving in through the code so i don't really have this is going to be a weird show in the sense that we don't really have a silver bullet um you know maybe this is an opportunity for someone to like invent something totally novel

but uh you know yeah i agree with patrick that the generators kind of cause people to write very odd comments and not very well structured comments on the flip side if people um use the generators but write only the important comments then the generated output doesn't look very good. It's not complete, yeah. Yeah, because what the generator will do is it will print all of your functions, but then the majority of your functions will look very bare and it'll look very bizarre.

In general, that's a problem with generators where you might have, like let's say you have a helper function, sort array or something like that. And it's just helping your class do something. Maybe it's even private. The generators, now there are rules or maybe they won't generate docs

on private functions and things like that. But you're still gonna encounter cases where things are basically gonna show up in the documentation that don't matter. Like a lot of the functions probably don't matter to 99% of your audience. And so all of that, yeah, I think, you know, maybe generators, but with a lot of handholding could be the way to go. But you brought up a really good point though a minute ago about saying like part of this is,

and you're sort of elaborating on it now like part of this is how many people are going to be using your code if you're writing some like deep internal something that isn't really going to be shared by a lot of people um then the kind documentation is important but the kind of like put it out to a website maybe less so but something like you know tensorflow or something that's going to be a common utility then it's it might be worth investing in right and spending the ongoing cost of maintaining that's a hard balance to strike because i think a lot of times we were talking about before this grows organically you don't think like oh this code is going to be used by everyone uh and and then it is i guess that's a good problem to have but uh you know or you could think oh man so many people are going to want to use this come and spend so much time

documenting it and then you know it never is yeah that's that's yeah you want to do lazy evaluation here like you want you want your project to get uber popular and then to document it as an uber popular project. But that's tough to do too. Yeah, I mean, well, I'll put it on your plate. Let's say you inherited some project that had, like you inherited Firefox, the code base. Oh, dear.

And it has, you know, maybe it has some inline doc like how would you document something like that like what would what would be the best it's tough but i mean like you're like firefox is a good example it's like lots of people and i don't i have no idea about specifics of firefox but lots of people use firefox but most people don't use it as like an sdk so the kind of good point the kinds of things like what is their uh javascript engine called i forgot now um but um gecko or something is that oh no no uh spider monkey yeah yeah spider monkey okay so i'll take your word. Spider monkey, like he probably needs better documentation than like the font renderer. Yeah, that makes sense. I'm picking stuff up.

But right, like trying to understand like as a whole, Firefox probably doesn't need equal documentation. So I guess it's the same thing like we were talking about in the files. It's recursive. Oh, dear. recursive oh dear um so yeah maybe if i had to come up with a strategy here i would say if you're writing something that starts to attract a broad brace a broad base of developers like let's say more than 500 developers or something like that or you're building an sdk where the goal is to have thousands of developers like that is the sole most important goal then uh go this generator route and take the time and effort to do all the manual curation and and stuff like

that so that it it you've pruned out all the meaningless stuff and you you um you document everything for the stuff that matters but then for every other part of your system or for every other thing you work on, yeah, just skip the generator and do the comments, you know, kind of yourself and the function and all that. I will say actually a lot of the ones I've used, Java docs are pretty good because I feel that if you use them just in the minimally intrusive way they're pretty helpful and even if you never generate the docs like i i don't think i've ever generated java docs the output i don't know i don't even know i wouldn't even know how to do it actually so i'm pretty sure i've never done it before um i've done doxygen and sphinx we have njs docs so i've never done java docs either i've only seen them but i will say that i have read lots of java doc comments in source code and that for the most part that when someone people go kind

of sort of crazy overboard i think they they do strike a decent balance like you can use it as a sort of slightly more structured comment yeah and then it's just sort of this side benefit that it also happens that if you do that you could get this generated documents yeah actually we should explain that a little bit so so the way these generators actually work under the hood is um you know in the generator documentation they're going to explain you know specifically how you need to document, whether it's a function, a class, whether it's the top of the file, a module, in the case is what it's called in Python, or a variable name, so on and so forth. It's going to tell you, look, if you want to document this parameter of this

function, this is exactly what you need to write. It's usually some preamble text or something like that. And that's going to let the generator know the context of what you're about to say. And then you write your comment. And maybe it's based on a line break or based on two line breaks or something like that. That's how it knows to reach the end of that. And then what the generator does is it will recursively parse through all of your source code pull out all of those relevant comments and the code that it pertains to it's usually just based on the code that is immediately following the comment and then it will it will generate and it can generate a lot of things html it could generate a p a PDF. One of these generators could generate all of these different formats.

And so you could literally just get a PDF with all of this documentation and print it out and give it to somebody and say, here's the manual of my code. So in that sense, it's really cool. But as we talked about, it has to be done. The auto-generated stuff isn't that elegant. Yeah, so in that sense, it's really cool. But as we talked about, it has to be done, you know, the auto-generated stuff isn't, you know, that elegant. You still have to do some hand-holding.

Have you, I've actually, I used Doxygen for my PhD code. So my PhD project was, like, relatively popular. I don't know. Let me look it up. Oh, dear. Yeah, now it's probably... I'm going to feel bad. No, don't end this with me feeling bad. Well, this is like years and years of work with no pay.

So you should not feel bad at all about this. Yeah, and I used Doxygen for that. And i felt like it was it was pretty reasonable i i want to bet probably nobody looked at it um but uh it kind of one thing it does is it kind of enforces you put some pressure on you to document everything because it looks weird when you generate this document and half the stuff's empty while you're looking that up i mean i think documentation in general is one of those things you generate this document and half the stuff's empty. While you're looking that up, I mean, I think documentation in general is one of those things that everybody feels we could do better at. And I don't know that anyone...

I don't think there's exactly a clear best balance of it. So be practical, but do write documents. Don't be the guy or gal on the team that says, no documents, my code is amazing. It doesn't need documentation. Yeah. Another thing is a lot of people don't, what's the word for this? Okay. A lot of people don't, if you're running a shell commands, you might not put that into a file and you should do that. So, a lot of people don't, if you're running a bunch of shell commands, you might not put that into a file. And you should do that. So in other words, the biggest documentation faux pas I've noticed is actually and maybe it's just the nature of the particular, you know, type of

programming I do. But the biggest mistake I see is not people not documenting the functions and things like that. But it's somebody has like this, this oh i run this and i run this command i run this command ends up being like literally like could be 10 commands and they just type them all in every time don't do that like like even if it's just one command make a bash script document the bash script and put it in the repository um so you'll notice if you go to the eternal terminal repo, I have a bunch of bash scripts that are just one-liners and they're not even that complicated, but it's just so easy to forget these one-line bash scripts.

Indeed. When it comes to shell, documenting shell and the flow is actually really important. All right, man. But yeah, I guess to conclude it, it's a living thing. Don't expect to have some silver bullet. Patrick and I, between the two of us, we've been in software. I mean, combined a lot of years too many years actually the other day uh anyway i'm going to change on this but yeah we've been

doing this for a long time embarrassingly long time and uh we don't really have a silver bullet here um you know in general the the like with anything like this it's just to stay on top of it. So personally, the stuff I'm doing at Now at Work, I've definitely gone loose on the documentation. It's something that wasn't very popular, and now it's becoming more popular. And so now it's time to say, okay, I'm going to take a week, and I'm going to just really clean up the documentation. And what that will do is it will actually force me to clean the code as well. Like organize the code into different, you know, organize

the files and things like that. And so just treat it like that, you know. Instead of trying to find some perfect plan in advance, you know, just look backwards instead of forwards. See how things are going and then kind of keep adapting. Alright. words instead of four words see how things are going and then kind of keep adapting all right all right thank you so much for uh supporting the show um through patreon audible also through your emails um this actually was a recommendation but it's a recommendation from

over a year ago and um i was just going through, you know, old emails and, you know, specifically looking for show topics. I saw this one. I thought, oh, this is a great topic. It could really appeal to anybody. And so I honestly didn't keep track of who told me what, but whoever suggested this, thank you. And for people who send us emails, you know, replied us on Twitter, Facebook facebook so on and so forth um thank you so much for your feedback and financially obviously is great keeps the servers running keeps the lights running um lets us buy uh microphones and things like that so we can kind of reach out to more people so um thanks a lot and uh we'll see you next month the intro music is Axo by Binar Pilot

programming throwdown is distributed under a creative commons attribution share alike 2.0 license you're free to share copy distribute transmit the work to remix adapt the work, but you must provide attribution to Patrick and I and share alike in kind.