Documentation

This is building better developers, the developer podcast. We will accomplish our goals through sharing experience, improving tech skills, increasing business knowledge and embracing life. Let's dive into the next episode. Well, hello and welcome back. We're continuing our season where we're talking about practical object-oriented programming. This episode, everybody's favorite. We're gonna talk about documentation. Now we talked about testing the last couple episodes and how critical that is because we are reusing our code. Documentation is right up there with it. Actually, a lot of times I've found that the documentation goes fairly somewhat hand in hand with the testing side of stuff. The source, the requirements that we're trying to meet are gonna point us to the validations, the tests that we need to run. And with those, that really should highlight what needs to be documented because we need to, you know, we need to think about this as this is something that I'm not the only one that's gonna use this or I may go away for six months or a year and then come back and try to use this. And I need to remember or have a way to understand how this was designed, what to expect when I use it. And that includes the most obvious stuff like the class name and whatever visible properties there are, methods, the method names and the signatures. But within those, we need to make sure that we really, we provide some detail. A lot of times what I see in particularly not like commercial software but stuff that's done internally is that there's some sort of a tool that's used because it's the easiest way to do it, that walks through our class and it basically builds like essentially a nice little webpage. It says, here's the class name, here's the, and maybe it does, maybe it shows the properties and it lists out the methods and the signatures. So it says, you know, method XYZ has these two, has a integer parameter, then a string parameter and it returns a string. Okay, great. Now maybe we try some self-documenting kind of code where the names are more meaningful than XYZ. So maybe it is, I don't know, give me a month name, give me a properly named month or something like that. And then I'm gonna send a parameter, so the return value is a string which is month name that we just call it that or we put a little comment on it. And then the parameter is integer and it's, you know, maybe we have something that says numerical month or something like that. That's still pretty limited. What we need to do is not just rely on our parameter names and our method names, but actually provide in our documentation, what are the expectations of those parameters? Are there limits? Is there an upper limit? Is there a lower limit? Is there a certain thing that's not supported? For example, a lot of times I see this with passwords where there's, and we see this in all kinds of systems, where you, you know, the idea is you just give it a password. Well, it turns out behind the scenes, there are certain characters that are not allowed as part of your password. Sometimes it's not like special characters. It's things like you can only have upper and lowercase letters and numbers. You can't have periods, you can't have exclamation points, you can't have pound signs, you know, hashtags, pound signs. You can't have ampersands, you can't have quotes, you can't have underscores, you can't, parentheses, all that kind of stuff. And then sometimes there's only certain characters that are supported. You know, it supports parentheses, but not quotations. It supports square brackets, but not squiggly brackets. Yeah, it's stuff like that. That needs to be part of our documentation. As well, and this goes back to, you know, some of what we were talking about with the testing. We have all these various states or types of responses that we can give in most cases. Maybe it's as simple as we can either give a valid response or an invalid response, but in which, in such case, that needs to be documented. What's a valid response? What's an invalid response? What should the user be looking for to validate that it ran properly? That, you know, what are the exceptions that this thing throws, if any? And what are the steps that a user can take based on those exceptions? So don't just say a legal string format exception. There should be, you know, is something that this thing supports. The documentation should have somewhere in there that says this is the format that we're expecting. So if you get an illegal format exception, here's what you need to look for is validate. You know, you can go manually validate your data that you give against our, what we call a valid, you know, valid parameter, valid string. You also wanna use, with your documentation, you also wanna make sure that there's any prerequisites or other used libraries or things like that. All of that is included. We run into that sometimes where we build out a system and underneath there are certain other classes or objects that we use that aren't immediately visible to the developer. And it could be very simple things. It may be like we have an attribute. Let's say we have a customer and it has within it an address class attribute. That address class has to be somewhere in the system. So there should be something that we document that says, oh, by the way, this uses the, you know, com.mycompany.address class. Then sometimes we can just group them all together and that's fine. But even within that, it should be apparent what classes are used by, you know, which class is used by what class. If I've got some properties or attributes that are other classes, I need to have that documented somewhere. I shouldn't just assume that this class is always gonna be within this bundle of classes. Yes, you could, you know, force that, particularly say, for example, if it's a commercial set of classes that, hey, there's this commercial library, use our bundle all the time. But, you know, that's still, that's just basically saying, well, here, just take this, you know, take my pile of code and use that, as opposed to giving the user some insight into what's going on. Now, if it's an internal class that some reason, you know, the user shouldn't see, then that's okay. But that class should be internally defined within the class that you're using. If there's something else that relies on, if there's some external thing that's relied upon, we need to document that. And that's, you know, that's one of those things we hide a lot that we, and we don't think about until we start moving things around. And then we realize that, oh, yeah, that's right. There's this other stuff that I refer to. Now, another thing that we failed to document a lot that can really bite us in the end is any sort of side effects or things like that. And this includes valid and invalid states in general. We need to, for example, let's go back to the idea of a constructor and an initializer. And let's say there's a, we'll call it a de-initializer and a destructor. Our class documentation should cover what is expected. If there's multiple constructors, what do they, is there any real difference other than the values that we're essentially preloading? Is there some sort of an invalid state that some of these may allow us be in that says, yes, you can use that constructor, but it's expected that you will follow it up by calling one of these three initializers. Or if you do this, then there are certain methods that you're not gonna be able to use. Yes, we can see that with the exceptions and things like that, but let's document it so the user doesn't have to see an exception to find out that, oh, wait, I had this other thing I was supposed to do before I started to use the instance. Just really, I guess the way to test our documentation and the way to think through this is to just look at your document for your class. Does it really tell the whole story? Are there some things going on under the covers that probably would be useful for a developer to know? And now this does become tricky because obviously we want to, there's the implementation hiding that we wanna do, so there's some things that we don't even wanna mention because that could change. And it could change without changing any of the signatures of the class or any of the actual functionality of the class other than maybe it does a little faster or something along those lines. So documentation, I know it's not fun and it's one of those things that we tend to punt to the end and say, oh yeah, we'll come back and we'll document it. This needs to be something that we are much more aware of when we're building object-oriented code than other stuff. Because the other stuff could be one and done. It could be that it's once, we write it once and it's never really dealt with again. And of course all the code's available and all that kind of stuff. Object-oriented by its nature says that we are going to pass this on to somebody else. Even if we think this is an object-oriented application that is a one-off, if it is a one-off then maybe we don't really need it to be object-oriented. And even if it is, then we probably still need to document those objects so that somebody coming back a year from now does not having to guess their way through our code. I mean, this is really a general document your code kind of thing, but object-oriented is more so because we need to help them not only just understand how this code works to solve a specific problem, we have to help them understand what is the generic use that this class should provide to them. That brings us to the challenge of the week. That's one of those convicting kind of challenges. When was the last time you sat down and actually looked at and or documented your code? And I don't mean like a quick little comment here or there, but I really like, you know, walked through and said, okay, am I, are all of my methods not only documented, but up to date? Because we get that a lot. We go in, we write everything out initially sort of like a skeletal structure. We put some comments in because we're just really great developers and then we write code and the comments are out of date. And that may be the worst kind of documentation because not only is it not, it's not that it's not there, it's wrong and it's up to the user to figure out where is it wrong. So please don't do that. So take a look, challenge, get out there, take a look, maybe catch up a little bit on your documentation, you know, especially paired with the last couple of episodes, maybe spend a little time this week catching up on technical debt and let's get some documentation. Let's get some tests out there, some unit testing done and feel a little more confident in our code at the end of the day or the end of the week. That being said, I'm gonna go out there and let you get to your day or your week. And as always have yourself a great day, a great week and we will talk to you next time. Thank you for listening to Building Better Developers, the Developer Nord podcast. For more episodes like this one, you can find us on Apple Podcasts, Stitcher, Amazon and other podcast venues or visit our site at developernord.com. Just a step forward a day is still progress. So let's keep moving forward together. There are two things I wanna mention to help you get a little further along in your embracing of the content of Developer Nord. One is the book, The Source Code of Happiness. You can find links to it on our page out on the Developer Nord site. You can also find it on Amazon, search for Rob Rodhead or Source Code of Happiness. You can get it on Kindle. If you're an Amazon Prime member, you can read it free. Lot of good information there. That'll be a lot easier than trying to dig through all of our past blog posts. The other thing is our mastermind slash mentor group. We meet roughly every other week and this is an opportunity to meet with some other people from a lot of different areas of IT. We have a presentation every time. We talk about some cool tools and features and things that we've come across, things that we've learned, things that you can use to advance your career today. Just shoot us an email at info at developernord.com if you would like more information. Now go out there and have yourself a great one.