Latest / DevQuestions with Tim Corey / 146 How Do I Document My Code?

Transcript

146 How Do I Document My Code? · DevQuestions with Tim Corey

• 0:00
  SPEAKER_00: Welcome to the Dev Questions Podcast with Tim Corey.
• 0:03
  SPEAKER_00: Join us each episode as we tackle the questions you are asking about a career in software development, understanding the industry, and new technology.
• 0:12
  SPEAKER_00: If you're just starting out or you want to grow stronger as a developer, this is the place to get your questions answered.
• 0:19
  SPEAKER_00: Now, here's your host, expert developer and online educator, Tim Corey.
• 0:25
  SPEAKER_02: How do I document my code?
• 0:28
  SPEAKER_02: How to make sure that I have all the information I need without having too much documentation that it becomes cumbersome.
• 0:35
  SPEAKER_02: Okay?
• 0:36
  SPEAKER_02: This is a question that came up on the suggestion site, and it's one I want to tackle in today's episode of DevQuestions.
• 0:42
  SPEAKER_02: Now, there's two different types of documentation that you might be talking about.
• 0:47
  SPEAKER_02: So let's clarify.
• 0:49
  SPEAKER_02: There is user-facing documentation, which is how does the application work, how I interact with it, what processes do I follow, and so on.
• 0:58
  SPEAKER_02: That's not what we're talking about today.
• 1:00
  SPEAKER_02: Instead, we're going to talk about developer documentation, documentation for your fellow developers, for the person that comes after you, for the rest of the team, and so on.
• 1:09
  SPEAKER_02: That's developer documentation, code documentation.
• 1:14
  SPEAKER_02: So let's talk about some ideas for how do you document your code?
• 1:20
  SPEAKER_02: Because they are going to be different per organization, but I think there's at least some ideas here that you can think through so that you can have a better solution for your organization.
• 1:32
  SPEAKER_02: First of all, I highly recommend, if you can, use GitHub.
• 1:37
  SPEAKER_02: Now, GitHub is not just for open source.
• 1:40
  SPEAKER_02: You can use it with closed source applications and projects.
• 1:44
  SPEAKER_02: I do.
• 1:45
  SPEAKER_02: I have quite a few closed sourced projects that are on GitHub that we work together as a team on that I would not want to have just out in the public as open source or viewable.
• 1:57
  SPEAKER_02: So GitHub is not just for open source projects.
• 2:02
  SPEAKER_02: So let's get that out of the way.
• 2:04
  SPEAKER_02: But now, why use GitHub?
• 2:06
  SPEAKER_02: What does GitHub have to do with documentation?
• 2:08
  SPEAKER_02: Well, when you have a bug that comes up, where do you put it?
• 2:13
  SPEAKER_02: Do you have a bug tracking system of some kind?
• 2:15
  SPEAKER_02: This is where GitHub really shines because it provides you with the issues.
• 2:20
  SPEAKER_02: And you can have an issue list that even non-developers have access to.
• 2:25
  SPEAKER_02: And you can put the information there.
• 2:27
  SPEAKER_02: Why is that important and what does it have to do with documentation?
• 2:30
  SPEAKER_02: Well, when you work on an issue, you associate a commit, the set of changes, to that issue.
• 2:39
  SPEAKER_02: And you say this commit either fixes this issue or is part of the fix for this issue.
• 2:45
  SPEAKER_02: Let's say you put three or four commits against a specific issue, and then you create a pull request.
• 2:51
  SPEAKER_02: And then you say, yes, this bundle of commits is the fix for issue number seven.
• 2:58
  SPEAKER_02: Well, then you commit that and you have a pull request, and the person approves that pull request, and you have discussions about that approval, and then you move that into your uh release pipeline, and it eventually gets released.
• 3:16
  SPEAKER_02: Well, now when a person looks at a file, a piece of code, they can say, what's the history on this code file?
• 3:27
  SPEAKER_02: And they can see the various changes that have happened to the file.
• 3:31
  SPEAKER_02: But they can go deeper and they can say, Oh, I can see that this fix right here was because of this specific issue.
• 3:41
  SPEAKER_02: You see how that works for documentation?
• 3:43
  SPEAKER_02: Now it's not just the code changed, it's the code changed because.
• 3:48
  SPEAKER_02: And now you can see even the discussions about why those changes happened.
• 3:54
  SPEAKER_02: So this way, if you had a back and forth about, I think it should be this, no, we we know it should be this because of X, Y, and Z, you have that history to go back to.
• 4:06
  SPEAKER_02: This is really important when you have things that that might change back or might want to be changed back.
• 4:12
  SPEAKER_02: Maybe the way you're doing things doesn't seem as intuitive, but there's a reason for it.
• 4:18
  SPEAKER_02: Well, if you have an initial set of ways of doing things, and then you make a change and say, I know it doesn't seem intuitive, but this is a better way because of this issue, and because of what it fixes, then you you aren't as likely when a new person comes in to have them try to roll that back.
• 4:38
  SPEAKER_02: Because they can see, oh, that'd be rolling back this fix.
• 4:43
  SPEAKER_02: I shouldn't do that because it would bring this issue back.
• 4:47
  SPEAKER_02: So again, documentation.
• 4:49
  SPEAKER_02: It also allows you to say these are the things that have changed in a given release.
• 4:55
  SPEAKER_02: So you can see, okay, I have 18 bug fixes, I have five new features, I have you know three major projects that have been accomplished in this release.
• 5:06
  SPEAKER_02: So that's also a form of documentation.
• 5:10
  SPEAKER_02: GitHub allows for all of this under one roof.
• 5:14
  SPEAKER_02: That's why I love it.
• 5:15
  SPEAKER_02: There are other tools like it.
• 5:17
  SPEAKER_02: Azure DevOps will do something very, very similar.
• 5:20
  SPEAKER_02: So you can use other systems, but the comprehensive system is really important.
• 5:27
  SPEAKER_02: If you use an external tracker for issues, well, you can connect them to commits, but sometimes you don't have that same history.
• 5:36
  SPEAKER_02: So just look at that.
• 5:39
  SPEAKER_02: All right, number two code comments.
• 5:43
  SPEAKER_02: I know some people hate code comments, some people loathe them way too much.
• 5:47
  SPEAKER_02: I think there's a balance here.
• 5:49
  SPEAKER_02: I think it's a middle ground.
• 5:50
  SPEAKER_02: So I would recommend code comments for tricky bits.
• 5:54
  SPEAKER_02: If there's a little bit of code that that might be a really weird way of doing things, but you figured out something, you got creative, which can be a bad thing as a developer.
• 6:04
  SPEAKER_02: When you get too creative and too outside the box, then you come up with some weird things that maybe you could do better by making it simpler.
• 6:11
  SPEAKER_02: But if you have to come up with some kind of tricky solution, then document it.
• 6:16
  SPEAKER_02: Put some code comments right next to it and say, this is why I did this.
• 6:20
  SPEAKER_02: You'll still have the commit.
• 6:22
  SPEAKER_02: You'll still have the maybe the issue attached to it.
• 6:26
  SPEAKER_02: So there's still that, but that specific bit of code, it's better to have some more documentation against it.
• 6:34
  SPEAKER_02: One of the areas for this is a regular expression.
• 6:38
  SPEAKER_02: Maybe you have a regular expression that tries to validate email addresses.
• 6:43
  SPEAKER_02: That's a whole thing because really there's no way to validate an email address.
• 6:47
  SPEAKER_02: There's just no way.
• 6:49
  SPEAKER_02: Um, besides saying it has an at symbol and it has a dot, that's about it.
• 6:55
  SPEAKER_02: Because other than that, you can have so many different ways of doing an email address, long, short, it's just a mess.
• 7:03
  SPEAKER_02: So knowing how to do that well is gonna be tricky.
• 7:08
  SPEAKER_02: So you create a regular expression that gets you 99% of the way there.
• 7:11
  SPEAKER_02: And you say, you know what, that's good enough.
• 7:13
  SPEAKER_02: We're gonna keep to this particular regular expression.
• 7:16
  SPEAKER_02: But if you look at it, it's gonna be this long, and it's going to have you know tons of different characters in there.
• 7:22
  SPEAKER_02: That can be tricky to read.
• 7:24
  SPEAKER_02: So explaining above there, saying these are the things it checks for, this is how it processes, that can be really helpful.
• 7:32
  SPEAKER_02: A word of caution here.
• 7:34
  SPEAKER_02: This is where the no code comments people will come.
• 7:38
  SPEAKER_02: Because if you do that, you have to be extremely cautious about making changes to that tricky bit of code.
• 7:49
  SPEAKER_02: Let's say it's a regular expression.
• 7:52
  SPEAKER_02: You you validate an email address and you realize, oops, we forgot about the.co domain extension.
• 8:00
  SPEAKER_02: Well, then you make a change to your regular expression to handle that.
• 8:04
  SPEAKER_02: And you forget to update your code comment.
• 8:07
  SPEAKER_02: Now your code comment says one thing, your code says something different.
• 8:12
  SPEAKER_02: That's a problem.
• 8:13
  SPEAKER_02: So you have to be meticulous about changing code comments when you change code.
• 8:19
  SPEAKER_02: This is why, when you have a review process for code, so you do a code review wherever that is in the process, that's one of the things to look for.
• 8:30
  SPEAKER_02: If you change the code near a code comment, did the code comment change?
• 8:36
  SPEAKER_02: That's important.
• 8:37
  SPEAKER_02: Okay.
• 8:38
  SPEAKER_02: But I do believe that those code comments can be very valuable.
• 8:42
  SPEAKER_02: Now, number three, I would recommend creating a wiki of some kind to document processes.
• 8:50
  SPEAKER_02: This can be as simple as how do you set up a new dev environment?
• 8:54
  SPEAKER_02: How do you push to uh to the main development server?
• 8:59
  SPEAKER_02: How do we move through development staging and production?
• 9:05
  SPEAKER_02: How do we um you know onboard a new user?
• 9:08
  SPEAKER_02: All these processes that don't even have to necessarily be directly connected to your code should be documented in some place essentially.
• 9:17
  SPEAKER_02: I recommend a wiki, um, something that's even just markdown files.
• 9:22
  SPEAKER_02: Uh for example, I've used the tool Obsidian in the past, where it just essentially takes my markdown files and creates a little structure out of it, giving a little bit more visual ability to synchronize them and change them and track them and all the rest.
• 9:38
  SPEAKER_02: It's good for personal, I'm not sure it would be good for a team.
• 9:41
  SPEAKER_02: But what it does is it keeps things simple.
• 9:44
  SPEAKER_02: When you make a wiki, don't go crazy.
• 9:48
  SPEAKER_02: Don't make all this structure and all these subfolders and subcategories and all the rest.
• 9:54
  SPEAKER_02: That's not what you want to do.
• 9:56
  SPEAKER_02: You want to keep it as simple as possible.
• 9:58
  SPEAKER_02: That's why, again, going back to GitHub, they have a very simple just markdown files for a wiki.
• 10:04
  SPEAKER_02: Because then you can just drop things in, change things around by just putting more files in, putting a folder in and putting more files in there.
• 10:11
  SPEAKER_02: So it's very simple to create some documentation that you can search on and document some of those big processes.
• 10:20
  SPEAKER_02: Now, that's kind of the what to do for documentation.
• 10:24
  SPEAKER_02: Let's talk about what not to do.
• 10:27
  SPEAKER_02: First off, don't put code comments everywhere.
• 10:32
  SPEAKER_02: This is a big red flag.
• 10:34
  SPEAKER_02: Don't do this.
• 10:36
  SPEAKER_02: Like I said, when you make a change to your code, the code comment needs to change along with it.
• 10:42
  SPEAKER_02: Otherwise, you're lying to yourself, you're lying to your other developers, you're lying to the person that comes after you.
• 10:49
  SPEAKER_02: You don't want to do that because naturally we will read code comments and we can sometimes skip over the code or go, yeah, I got it.
• 10:59
  SPEAKER_02: Imagine for a minute that you have an if statement that says, if um if age, you know, is of age, okay, is of age.
• 11:10
  SPEAKER_02: And it's just a variable, it's a Boolean, so you're just checking, is that true?
• 11:14
  SPEAKER_02: And then you put a comment that says, checks to make sure that the person is of age.
• 11:20
  SPEAKER_02: And then you go, oh, no, no, no, no, that was backwards.
• 11:23
  SPEAKER_02: I need to say if not is of age.
• 11:26
  SPEAKER_02: And so you put the exclamation point in front of is of age, which blends in really it blends in a lot, which is why I prefer to say equals false.
• 11:34
  SPEAKER_02: But if you say exclamation point is of age, but don't change the code comment, the code comment says checks to make sure the person is of age.
• 11:44
  SPEAKER_02: Well, now that's in direct conflict with the code, but if you miss that exclamation point, you might go, yep, got it, and have a wrong impression of what's going on.
• 11:54
  SPEAKER_02: So don't put code comments everywhere.
• 11:58
  SPEAKER_02: It makes things too difficult to keep up and maintain.
• 12:02
  SPEAKER_02: It makes it too likely they'll make these change these changes that don't align your comments with your code.
• 12:10
  SPEAKER_02: Number two, this kind of goes along with it, but don't create comment headers on files.
• 12:17
  SPEAKER_02: Now, I'm gonna duck right here because probably half of you already are.
• 12:21
  SPEAKER_02: Um, I've worked in organizations where we did this.
• 12:24
  SPEAKER_02: You do it on even uh things in SQL or other places.
• 12:29
  SPEAKER_02: I don't recommend it.
• 12:31
  SPEAKER_02: I don't recommend doing this.
• 12:32
  SPEAKER_02: And there's a couple reasons why.
• 12:34
  SPEAKER_02: First of all, not every file deserves some kind of explanation of what the file does.
• 12:40
  SPEAKER_02: When you have a person controller, what do you say in the header?
• 12:45
  SPEAKER_02: This is a controller for the person objects.
• 12:50
  SPEAKER_02: Okay, that's not helpful, that's not helping anybody.
• 12:53
  SPEAKER_02: And you say, well, what we do is we use it for tracking all the changes to this file.
• 12:58
  SPEAKER_02: Okay, kind of like what Git's already doing.
• 13:01
  SPEAKER_02: Like, why are you not using source control?
• 13:04
  SPEAKER_02: Because that's exactly what source control does for you.
• 13:06
  SPEAKER_02: That's one of the many things it does for you.
• 13:09
  SPEAKER_02: So the other thing is, yeah, you always change it, do you always update it?
• 13:14
  SPEAKER_02: Well, we've forgotten before.
• 13:16
  SPEAKER_02: Yeah, okay, that's the same thing with code comments.
• 13:19
  SPEAKER_02: And so soon you find out that half these headers don't really matter.
• 13:24
  SPEAKER_02: And so you start skipping over them, you don't really pay attention to them.
• 13:28
  SPEAKER_02: Okay, so why are you doing them?
• 13:30
  SPEAKER_02: So again, I would skip those.
• 13:33
  SPEAKER_02: Number three, don't allow massive commits.
• 13:38
  SPEAKER_02: So when you are committing all your changes to Git or whatever source control system you use, recommend Git, but whatever.
• 13:46
  SPEAKER_02: Whatever system you use, don't have massive commits.
• 13:51
  SPEAKER_02: Imagine you were implementing a pretty complex feature.
• 13:54
  SPEAKER_02: It's gonna change, I don't know, five files, right?
• 13:58
  SPEAKER_02: You're gonna write uh 500 lines of code, 100 per file.
• 14:02
  SPEAKER_02: Okay.
• 14:03
  SPEAKER_02: If you commit that as one commit, what have you changed?
• 14:08
  SPEAKER_02: Well, you've changed file A, file B, file C, file D, and file E.
• 14:12
  SPEAKER_02: And now in there, we've changed this, this, this, this, and this.
• 14:17
  SPEAKER_02: Okay, so when it comes to documentation, and a person later is working on file B, and they say, why has this file changed?
• 14:26
  SPEAKER_02: Or how has it changed over time?
• 14:28
  SPEAKER_02: And they see this last change and they see all these changes.
• 14:34
  SPEAKER_02: And then they go to the commit message and it's got a list of 30 things that happened, or even worse, it has one line that doesn't explain anything.
• 14:43
  SPEAKER_02: Okay.
• 14:44
  SPEAKER_02: Massive commits kind of hurt your documentation.
• 14:49
  SPEAKER_02: So make small atomic commits.
• 14:53
  SPEAKER_02: If it's okay to have a commit that has one line in it, that's okay.
• 14:57
  SPEAKER_02: It's okay to say, hey, you know what?
• 15:00
  SPEAKER_02: This small piece, that's a commit.
• 15:04
  SPEAKER_02: So having multiple commits doesn't hurt.
• 15:07
  SPEAKER_02: And what it does do is it keeps the ability to have that documentation be more specific to that one thing you're doing.
• 15:14
  SPEAKER_02: Otherwise, when you look at file B and look at the commit message and it has 30 things that have happened, which one applies to line 29?
• 15:23
  SPEAKER_02: Don't know.
• 15:25
  SPEAKER_02: That's why having more atomic commits is helpful.
• 15:29
  SPEAKER_02: Now, number four, don't skip source control.
• 15:35
  SPEAKER_02: I've been organizations, your source control is a zip file that you create every now and then about, you know, with all the changes, you work in production.
• 15:44
  SPEAKER_02: Yeah, I've been there.
• 15:46
  SPEAKER_02: Don't do that.
• 15:47
  SPEAKER_02: That makes things so much harder on yourself.
• 15:50
  SPEAKER_02: You're losing out on the ability to have this built-in documentation, the ability to communicate with your past and future selves, and the ability to re-understand as a team how this thing works, having a history of what's going on, as well as protecting your code against code loss, making sure that the changes you're doing apply to what you're fixing and being able to undo changes and so many other things that source control does.
• 16:20
  SPEAKER_02: But a big one is that documentation.
• 16:24
  SPEAKER_02: And number five, and the most important one, don't make documentation hard.
• 16:32
  SPEAKER_02: This is one that I see violated all the time.
• 16:36
  SPEAKER_02: You get super enthusiastic about documentation.
• 16:39
  SPEAKER_02: You say, you know what, we're gonna buy this tool.
• 16:41
  SPEAKER_02: This tool is awesome.
• 16:42
  SPEAKER_02: It does all these things where it creates a PDF and it creates an online website and it links everything together and it has all these features and it allows it to do all this stuff.
• 16:51
  SPEAKER_02: That sounds great.
• 16:53
  SPEAKER_02: But the problem is that it takes a lot of work to do.
• 16:58
  SPEAKER_02: And more importantly, a lot of work to update and maintain.
• 17:04
  SPEAKER_02: So just like with the code comments, if you have a separate system where you're making documentation, well, then what happens is that it is going to have this problem where you can change the code and forget to change the documentation, and now all of a sudden they're out of sync.
• 17:20
  SPEAKER_02: And even worse, if then your documentation is not in your source control system, you can't make the change until that change goes live.
• 17:29
  SPEAKER_02: Now you're trying to keep track of, okay, when that change goes live, make these changes to the documentation.
• 17:34
  SPEAKER_02: It's not going to happen.
• 17:36
  SPEAKER_02: What happens is people get very enthusiastic to start.
• 17:40
  SPEAKER_02: They get very enthusiastic about the technology, about the systems and the ways it can work and all this shiny stuff.
• 17:46
  SPEAKER_02: And then over time, it slowly fades away.
• 17:51
  SPEAKER_02: And that shiny wears off.
• 17:54
  SPEAKER_02: And what happens is you have a system that has old documentation that's never been updated, that no one really touches anymore.
• 18:02
  SPEAKER_02: And it's the only thing we actually have for documentation.
• 18:05
  SPEAKER_02: So new hires get that, but doesn't really apply anymore, and we've got a mess.
• 18:11
  SPEAKER_02: Okay.
• 18:12
  SPEAKER_02: That's what happens when you make documentation hard.
• 18:15
  SPEAKER_02: Documentation needs to be as simple as possible, as intuitive as possible, and as close to your already existing processes as possible.
• 18:26
  SPEAKER_02: That's why I encourage you, that's why I encourage you to use source control systems like GitHub to kind of be that documentation as well.
• 18:35
  SPEAKER_02: You can use them to add more things.
• 18:38
  SPEAKER_02: You can make small commits that describe what's happening.
• 18:42
  SPEAKER_02: You can do other things to make sure that your code comments are changing when your code changes and all the rest.
• 18:49
  SPEAKER_02: But you can use those tools to make that documentation easy.
• 18:54
  SPEAKER_02: And by doing so, it's much more likely to happen.
• 18:58
  SPEAKER_02: And the argument is well, this more complex system, that's what we really need.
• 19:03
  SPEAKER_02: I get that.
• 19:04
  SPEAKER_02: But the problem is it's not going to work.
• 19:07
  SPEAKER_02: So which would you rather have?
• 19:09
  SPEAKER_02: A broken system that, if it was done right, would be shiny?
• 19:13
  SPEAKER_02: Or a system that's not perfect and could be better, but is current and up to date and has a history to it.
• 19:22
  SPEAKER_02: I think the choice is obvious.
• 19:25
  SPEAKER_02: Okay.
• 19:26
  SPEAKER_02: Have a system that does work, that has some things, and grow over time.
• 19:31
  SPEAKER_02: Maybe you do end up having some kind of documentation system alongside.
• 19:36
  SPEAKER_02: But make sure you grow it slowly over time.
• 19:39
  SPEAKER_02: Implement small pieces of it and grow it and see how it works.
• 19:43
  SPEAKER_02: But the very core, your documentation should be in your source control system.
• 19:50
  SPEAKER_02: Okay?
• 19:50
  SPEAKER_02: So I hope they answered your question.
• 19:52
  SPEAKER_02: Thanks for listening.
• 19:53
  SPEAKER_02: As always, I am Tim Corey.
• 19:55
  SPEAKER_01: Thank you for joining us for this episode of Def Questions.
• 19:58
  SPEAKER_01: Tim is committed to making it easier for you to become a developer.
• 20:02
  SPEAKER_01: If you would like to help make more content like this possible, please like, subscribe, rate, and share Dev Questions.
• 20:09
  SPEAKER_01: You can also send your questions to questions at IamTimcorey.com.
• 20:14
  SPEAKER_01: Until next time, remember, you are too smart and your time too valuable to waste it making all the mistakes Tim did.
• 20:21
  SPEAKER_01: When you're ready to learn to think and code like a professional developer, head over to imtimcore.com and enroll in a course.