 Yeah, so to extend that, you know talking about documentation So you've all read the the comic Yeah, not just waiting comments in your code anyway, so so let's take Let's make some distinction between documentation versus comments So comments obviously comments in your codes. They start in target and talking about doc blocks We're just quick little snippets to say what's what's happening So, you know, you're helping guide any other developer, especially in in that collaborative space like like the WordPress open source community You don't want to be the only one working on it like that's the point of open source is to say Okay, I've come up with this idea. This is the code that I've built around it Who wants to help me? But it also helps good good comments can help you build your developer documentation Whereas documentation it can help the end user so that could be a developer, but it's usually geared more toward the person WordPress parlance installing the theme installing the the plug-in and giving them step-by-step instructions on you know any Stuff that's outside of the box of what WordPress would do. So, yeah code comments So so why would you want to comment? I mean I've got my point. I'm fully open to any of you You know chiming in so like Why would you want to put comments in your code? Well? You know you want like I said earlier you want other people to help you out with your code and you know Not everyone writes obvious code, but you know that's the goal, but that's not always the case So it's for you to understand your code because if you wrote it and then six months later. You have to go back to it You know what I I mean? I've looked at some of my code from eight months ago and go What the heck was I thinking? like really Yeah, again going back to the ease of creating co-reference. I'll touch on that a little bit later, but no, but Who's heard of PHP documenter anybody no PHP documenter So it's it's basically it's a it's a Framework that you essentially feed it your code and As long as you have good doc blocks and good commenting within your code It will actually create a reference a code reference for you so Think about the WooCommerce API documentation It's I don't know that they use PHP documenter But I'm pretty sure they used an automated tool and then filled in the blanks that the comments didn't Didn't put in there, but you yeah any time Usually once it's done like that you basically do it once your release is ready And then it spits out HTML Because it's like a process. It's it's not something that that gets like it's not something that's dynamic It's something that's static it's created and you dump it in You know on your on your server or on a s3 bucket or something like that But it's essentially all linked and you know shows all the different classes show how they enter relate as long as You've done that documentation process in like the the doc blocks sense Yeah, and to-do list for yourself, so if there's a There's a feature that you want to integrate, but it's not critical you can put that in Or even if it's as you're going and you say oh, I need to parse this string to into an array example, but You put it at to do and it'll actually put it in a lot of IDEs will actually call it out for you Well either highlight it or we'll actually put it as like an almost like an error or warning Saying you need to look at that later or whenever you open the file. It's like oh, hey, look at that and As I said before being a good open-source citizen if you want people to use your code if you want people to collaborate on your code Comments are going to help people get into it a whole lot easier and usually when it comes to open-source people are doing it because they like it And if you're making it difficult for them to do that, they'll just go on to a different project when so Somewhere on the fence of the usefulness of code and a lot of the a lot of this is more on the compiled Languages side of things so you're talking like a C and its Iterations Java that sort of thing because it does it doesn't do anything for the compiler. It's essentially writing code Twice because you're writing it for the compiler and you're writing it for the human looking at it later You know and in the case of JavaScript and CSS if you put a lot of comments and it's going to take up Bandwidth when someone downloads it they're downloading everything Including those comments unless you minify, which is obviously a good idea, but that's another discussion Yeah, I think always like Yeah, it might be an unpopular opinion, but comments are critical to your understanding other people's understanding it's it's The pros and way the cons every time to me Again, it might be an unpopular opinion. Sure Yeah, I am good touch on that. Yeah But you know what well, it's a discussion because we're a small group here. It's all good My So the point that I made I can't remember which side it's on but Yes, you should aim to write excellent code Two things that don't cover that that don't get covered there is if you want to get to a point where you're creating automated documentation That won't help you You'll get Like if if it's a I haven't used PHP documenter in a couple years But what it spits out is it looks at your comments first and then it looks at the method or function So if there's no comment then it'll just give you the the function and you know what variables it expects But if you're not explicit about what your function or method expects It doesn't know it says so like Create array You know Say data one Instead of data one being a string. It's expecting a string It'll just say mixed So even though your function would treat that as a string if someone passes an array It'll blow up Right, and I mean it's it's not at the end of the day. It's not a big deal because we're not You know as wordpress developers. We're not dealing with like high-scale high Volatility data, but It's a good idea to be a little bit more strict with yourself because again It helps people understand your code because it may it may be completely obvious to you But it might not be to someone else Even with good variable names and you know well structured code and all that Your understanding might be different from someone else's understanding But I was going to post a meme there, but it had intellectual property So I made my own so yeah where so your code should be self-explanatory Exactly what may be clear to you may not be clear to others Yeah, so use comments as a means to briefly explain the file the class or function using a doc block again because of The documentation tools that are out there and a code block using Or a comment block is what I meant to put there. No a code block. No, that's okay See if I had commented my own slides, I wouldn't understand anyway So yeah, if you're if you're wanting to just do like a code block That's within a function or something like that then you can use just a simple comment Some people will actually go to the lengths of actually creating a small doc block. I don't do that But your mileage may vary. Oh, yes. This is another good reason for it. It's funny Step judging me. So yeah, simple comments. I'm sure all of you know what Comments look doc block is more of the the interesting stuff. So this is a PHP doc So this specific doc blog is for a method within a class It's super super simple, but you kind of get the idea The parameter is there is expecting an array It kind of so it's it's essentially that it's if you're if you have multiple parameters You just do it on second line But param and then the type the name of it and an explanation of what's what that data should be And then return you want to actually see a return obviously But you know What the what the function returned or method returns and an explanation of it You don't necessarily need to do a description, but that's one of the things that's recommended especially around the duck You look like you have a question Some will pretty sure eclipse does if you're that nerdy I can be time at times, but I use PHP storm Which actually generates them properly and there are plugins that will read it But at the end of the day that this is for The two things other people reading your code and the automated documentation tools I think yeah You don't read it. No, that's right Yeah, I agree with you there, but if you want to bring someone else into into the fold Then it helps them because it's like oh, I don't have to read through the code. I just go. Oh, that's what it does Okay. Oh, I need to fix something that it's doing. Okay. It looks like it's there I think I'm sorry. No, go for it Don't feel like you need it for yourself or you're not doing anything collaborative because I found that with myself for a lot of time like for a long time I was involved with a lot of that stuff because I Just freelance everything Now that I'm actually taking on some of these other projects and realizing What a trigger How hard they are to figure out where anything is And you don't always know like how long Like, you know, your life times a long time a lot of things that happen You don't really know like where you're gonna be in the future Well, yeah, and I mean I I've been kind of going more along the lines of you know If you're a plug-in or a theme developer, but if you're doing something for a client and You know the thing that they always say is if you get hit by a bus what happens Not that I would wish that on anyone but I mean even if it's something as simple as you move halfway around the world and You no longer can deal with that client so they have to go find someone else you've done it so Let's say you've built a theme from scratch and a couple plugins from scratch for their site because nothing else fits Or it doesn't fit enough Okay, it's great. You're you're an awesome developer. Did you comment your code? If someone else has to take over what are they getting into again, you can create code that is very self-explanatory To you, but that doesn't mean that everyone can read your code and At the end of the day. Yes, they they will be able to read it because you know there are a plethora of PHP functions and WordPress functions and JavaScript functions that Are well documented everywhere else But then you're creating more work for that new developer to go and figure out if they haven't used it To go and figure out what each of these things do J s dot There we go. J s doc very similar Except in this case, they use the curly braces around what data type it is So now that WordPress has a very full fledged API Built-in rests API You might want to start looking into Depending on how you're developing if you want to use the rest API. I know a lot of people who are trying to go to more towards Using the WordPress backend and no front-end so though they call it headless headless WordPress so if you're creating or you're using More the API side of things well you might want to document that as well who's ever heard who's heard of apiary or Swagger swagger is the big one or at least it used to be so it's a It's an API documentation standard. It's basically markdown with a little bit of extra flair for For documenting like what you should be passing to this API what your expected return is what errors you could get you know, so API seem to use more of the The HTTP error codes than anything else I've ever seen so like 421 is unexpected entity, which means you've given it wrong data But basically what you're doing is you're expanding out The information that someone would need to access that API without touching your code So like you'll see Think of a good One that's used it. I've just done a lot of our team and I've done a few API documentations, but You know what I'll actually Show you what I did recently. It's not WordPress based, but you'll forgive me. Oh, that's not the right site Yeah, that's right one all right Actually, I don't have my phone on me I probably should have planned this Do you have another one in Here wow this projector is not happy. Okay, so this is an API So yeah, so just it's it literally is just a markdown document that has a Little bit more information when it comes to you know, what's expected What that's like what the different errors you can get This one doesn't really get into the nitty-gritty. So like with Some of the more complex ones you can actually it'll actually give you like kind of accordion style Where you have the different end points that you can hit and you click on it It will actually give you like a text Representation like like a paragraph of what you what this endpoint does but over on that side It actually shows you the JSON that They like that the API expects and then you scroll down and you see the JSON that Would be returned So it's really it's a really robust platform swagger does the same thing But if you're getting into Into using and building API is for the word for the WordPress JSON API and a restful API then you're gonna want to maybe look at this Especially for like the stuff that you're building on top of or if you're Expanding or if you're making your own Yeah, go for so PHP documenter is for PHP code This is for someone who isn't necessarily who isn't touching your code, but needs to get to your API So when I say API, I mean restful API where they're sending just JSON data Returning JSON data, right? However based on so if you're providing so let's let's flip this on its head a little bit Let's say what you're building is Very sensitive Or like the person that you're building it for is not wanting the code to be open source Then what you want is that but you want anyone or Specific people to go in and actually use the API, but not touch the code That's what this is for Exactly. Yeah Yeah, so yeah going back to so again It's it's it's gonna be very similar to a user Document and that you want to be verbose but not to verbose You want to give them as much information as they need and no fluff Yeah, and as I said give every possible use case error that you can think of So like if they pass a string that should be a number I Mean PHP is pretty good about switching it if it if it's a string with a number anyway Um Give them what would show them what would be returned? So like The go-to for incorrect data is as I said earlier for 21 And what JSON data would be sent back if any? Because I mean when it comes to an error a Lot of API's will just send an error code back with an empty data set But some people want you know a more robust Information because 421 Yes, it's a specific HTTP error code, but Your your code that created that API could actually send back data saying this field was Pass with this data and it should have been past with this all you know, there's there's varying Chatter about what those what that data like error data should be sent back That's completely up to you and your users And yeah, that's the other thing so the one that I was going to show you that I couldn't remember the URL for I have actually edited probably 30 times in the past six months Because someone said oh, what about this? Oh, I didn't think of that. It wasn't it was a project I inherited So that helps matters that you know, I didn't think of it But yeah, it's not it's not always readily apparent to you even if you've written it How your API will act especially because you're tapping into the WordPress API there might be something that you don't know about So Yeah Yeah, we kind of talked about this. Oh, yeah, that's the other thing. I've had at least four developers That use the API that I developed that I took over and said oh, this doesn't work Okay, did you read the documentation? Yeah, well, did you read the part that said this part doesn't work? Well, no, okay, we'll go back and read that part so I Actually took that chunk that says so that's the other thing about API talk apiary it actually creates a Code snippets for people to use But I still haven't figured out why their code snippet doesn't work For my API even though when you look at it and you dissect it it should But then when I go into another tool called Postman which basically tests apis The code that it creates does work So there's probably a flag that I just haven't really dug deep enough into that That postman sets but not apiary Yeah, so we talked about documenting the data structures Yeah, leave as little room for error as possible User guides so this is the one that I found the most interesting because I've never actually written a user guide But it kind of did some digging some research and there's kind of a profile prevailing theme Keep the jargon out of it So if there is internal jargon or developer jargon keep it out Well, if you were in the last talk talking about it's a Gutenberg and page builders Nick talked about, you know JavaScript developers coming into the fold because of how How Gutenberg is built What does that mean to an end user? You have to explain it but that was that you not that javascript javascript is sort of jargon, but At the end of the day, what does that mean for the end user? You say, oh, this is built on javascript. Okay What does that mean for me? I've never touched the line of code in my look. I'm not saying it's me But I never touched the line of code in my life. I'm installing a plug-in because it's built on javascript. What does that mean? What does that mean for my site? What does that mean for my customers? So keep the jargon out of it or if you if you need to explain it with jargon explain the jargon That's jargon leet. It's so leet it's Hacker speak basically for elite the exactly yeah Yeah Yeah, so like and know your audience is it is it's a novice is it for someone who's just starting out or do you know for a fact that it's going to be a Pro-user or a developer, you know, and is that developer new is that developer, you know Use plain language. Keep it simple. No long paragraphs Point form is actually better, especially when you're talking about like step-by-step instructions Don't get into like don't put like step-step-step and then a paragraph about what's happening at this point if it's relevant, okay? If the user could care less of it just keep it out. I don't think it's necessary. Yeah, that's another thing What does your project solve? I Mean that's If we're talking about a WordPress plugin, that's going to be your your front page Like what what does your plug-in do? Because sometimes the name You if you want to be creative with your name that may not tell the end user what it is or what it does So that first paragraph needs to be The elevator pitch What does your plug-in do? What is it gonna do for me? You know as I said step-by-step instructions frequently asked questions How and where to get support? Plug-in that the nice thing is that's that's kind of a built-in thing with with plug-ins Because it has it has the wordpress.org chat But yeah, so it kind of has that built in but if you get to a point where you're building Commercial plug-ins or like pay-for-support plug-ins you really go down to Where are those people going to get their support because if your plug-in isn't on the repository? Where are they going to go if it's just an email address? Fine But I would go so far as to have I like a user forum or Because I mean baby press Perfect perfect example. That's something to throw it real easy Trying to think oh Zendesk There's a half a dozen things that are Free for small sites and then maybe you need to start paying for if it gets a little bigger But yeah, I mean by all means you need to have a place that are like a knowledge base Where you know if someone asks a question you go Didn't you think of that write a small step-by-step or a small article about it? Screenshots did I mention screenshots? Yeah four types was it just for I probably should have done a little bit more, but no, you know when When they're when you're going through a step-by-step Bit screenshots are invaluable You know Depending on how someone learns will be You can you have the text and you have the image Some people will just look at the image and go oh, that's what happens there. They won't even look at the text so if if at all possible have as much Have as many images as you can that kind of stuff them through the process and This is my guiding principle when it comes to commenting to documenting to creating user guides If you were to so you're developing something it's amazing You're giving it out to people, but if they don't know how to use it Okay So it flipped that around if you went out Grab the plug-in because you knew that it would do exactly what you need to do But you had no idea how to use it because they didn't do documentation. How would that make you feel? like if you spent an extra Hour or five hours or ten hours because you knew that that person or that plug-in did what you needed to do But you just didn't know how to do it You're just creating headaches around the world. I'd be interested to hear and Chat about it. I agree and that's and that's where Yeah, oh, yeah Well, and that's and that's I said a couple times that brevity is key Give them enough information don't give them too much and that goes across everything that goes with commenting that goes with documentation whether it's for an API or or a user They the end user will not want to wade through paragraphs of Your life story I Just want to use your plug-in this Get over it, you know Yeah, exactly which button do I click I need to do this which button do I click? Well, when I was young Not that anyone does that but you're right in Commenting especially in commenting. I find user guides to be way too brief and not detailed enough At least on the plug-in repository But I don't know Oh For commenting. Yes, sorry for commenting. I find when It's it seems to be either end of the spectrum I Find very few and I will be the first person to be honest that I don't comment And I catch myself like I actually looked at The another Client thing that I'm working on. I haven't been documenting at all Like not crap. I need to go back and do that You know again, even if it's just the dock blocks for the classes the methods You know breaking up my CSS to be you know based on the screen or the the area of the site that I'm working on So that you're not wading through you know Think my biggest projects that I worked on not alone. I was 10,000 lines of CSS and The original person put it in one file And no comments So, I mean the nice thing was they were a little bit descriptive with their dibs So I was able to find things relatively easy But it still took me about three weeks to really get comfortable and this was like a long-term project So Yeah, I mean you're right. There there is there is a fine line between There that that line is that's good commenting This is too much. This is too little Where you land That's that's completely up to you and again It's it's going to come down to you the code that you write and the comments that you write May make perfect sense to you But I would almost err on the side of Too much versus too little yes, there is a good there's enough there There's a that you know that zone of the right amount, but I would Go a little bit more Because what again comes down to what you think makes sense may not make sense to someone else I So basically it comes down to as you said doing a dock block for a class and for your methods I Know a lot of Seen lots of classes where they have a dock block for each individual Class property. It's like okay. That's a little overkill But because like it's not doing anything when you declare it That's where you know a well named variable Is is better than a big piece of like a big dock block just for a variable name So yeah, but like going down my my my minimum is class method and If I feel the need I will like separate out a block and put a comment at the top like if there's like if a function or a method does This thing, but it has like kind of three steps. I'll chunk it out whether I put comments or not but if one part I write a little shorter for brevity's sake or for for Efficiency Then I will definitely put a comment above it saying this is what this does. I'm sorry. It's too short There's something you know and I usually put a joke in my comments somewhere There's at least one joke in every project that I've worked on But yeah, that's kind of that's kind of the minimum for me and then when it comes to JS is similar to PHP I try and do Objects where I can because that kind of again makes for more readable code rather than just a bunch of jQuery callbacks That can be kind of annoying but And then CSS it's kind of just depending on if you're doing, you know sass or less That makes it for more readable CSS, but at the end of the day depending on, you know who you're talking to what the Expectation is I will at least chunk out my my CSS and put like this is for these are home page styles Or this is a specific block style or these are block cells that sort of thing But again, it's it's completely up to you, but you know That's kind of my minimal Yeah, I think it does Well, and at the end of the day when you when it spits out if you haven't put a dock block It will be very obvious Yeah PHP documenter does I think it gives you a report once it's done So I would I would have to look into that but PHP documenter net I think Is the site but just do a search for PHP documenter and it's great actually I have Yeah But there if you want to take a picture that that's all the that's all the references PHP document yeah, PHP doc.org actually is But they had good JS documentation Standards so there were very much similar to a PHP doc. Yeah, yeah, yeah, no problem, right? Any other questions, you know good Thanks for coming out to work in Hamilton You