How Do I Document My Code?
HTML-код
- Опубликовано: 23 июл 2024
- What is the best way to document my code? How do I maintain both internal documentation as well as public-facing documentation? What is the best way to keep all of this in sync? These are the questions we will answer in today's episode of Dev Questions.
Website: www.iamtimcorey.com/
Ask Your Question: suggestions.iamtimcorey.com/
Sign Up to Get More Great Developer Content in Your Inbox: signup.iamtimcorey.com/
Great to see someone talking about documentation for developers. Some people seem to think developers can survive without any written documentation whatsoever when things get into maintenance mode. Code comments are mainly to help the person writing the code in the first place. Here's where I need to build this capability, here is where I need to move data around, etc. If you keep those messages high-level, the code can change underneath them and the comment still rings true. They also act as reference points when you are locating functionality (For instance, Where did I "DETERMINE HIGHEST-PAID EMPLOYEE"?). If useful to the next developer, that's a bonus.
Thanks Tim for having this channel and allowing suggestions and creating content to have discussions around. A couple of ideas and alternative views to share. One is similar to don't allow large commits and that is long-lived feature branches for the same reason. Long-lived feature branches can require wide sweeping changes and create large amounts of conflicts when trying to merge back and again create a large resolving commit. Second is the creation of code comments for complex or tricky code. I like your warning about keeping it up to date with any changes but it's a trap in that not only you have to be careful with it but everyone has to be careful with it and it doesn't always happen. So it's like putting a grenade with a trip-wire in the code. Time constraints and distractions can lead to it not being updated and then disaster. A better way is to document with variable names and method names and ultimately tests that break when altered incorrectly and warn the developer to be talking with other developers about the change. before altering the test and committing. Keep up the great work!
Tim, thank you so much for your great work. You don't have an idea of how much it helps me here. I subscribed to the All Access Pass of your courses and I intend to keep in the program for as long as I can. Thank you so much! Best rwgards from sunny 🇧🇷🇧🇷🇧🇷🇧🇷
I’m glad my content has been so helpful.
Thank you, Tim. Your content has been a great help for me.
You are welcome.
Great episode, dear Tim, and thank you for supporting us, and keep it up.
You are welcome.
Great video, Tim. I’m having this discussion at my organization right now, trying to get everyone on board with a standardized documentation system
Sounds great!
Nice succint set of points there Tim. Reminds me of what my old boss used to say to us: Don't create processes for the sake of processes as you'll only tie yourself down.
Thanks for sharing!
As always, Tim. Great video. With regard to code comments. My general rule of thumb with comments is that you should explain WHY the code is what it is, and not WHAT the code is doing. Your REGEX example might be a valid exception to that rule. So, as an example, I might have a comment that says "Used a direct ADO connection to data here because of XYZ limitation of the ORM". The goal is self-documenting code, which is one of the reasons naming things is so important, and so hard.
Thanks for sharing.
I would like to add, tests work as documentation, especially integration test. They will always be up to date and if you adopt BDD they can be part of your acceptance criteria for your users story's and work as acceptance tests. Again always up-to-date and if you then apply a changelog you can go back in t8me, se who did what, why and when.
Thanks for sharing!
Omg I’m working with some people that refuse to learn git. They create versioned files named with a date. Like htf do they know what changed. I have to manage their source control for them, and there’s always new files in the repo named with dates! Version control is a MUST
That’s rough.
I put headers in all my files, but the only thing I insert is a change history. That helps if I am moving a change through staging environments. I can then see at a glance if I have the correct version in a specific environment. It also can make it obvious if someone updated an old version of that file because a change record will be missing from the header. What you say in the change record is not as important as the record itself.
The TESTS are also a very good documentation when methods are correctly named. Thanks
You are welcome.
There are some good points here, thanks. One thing I suggest is to mark up protected and public members with XML-Comments. This will work automagically with intellisense, and is compatible with many tools, including Swagger/Swashbuckle. There are tools to make this less onerous that infer from type names, and you can review/adjust as needed.
That is a helpful feature.
13:30 I've been nagging my manager to consider git for source control for this reason.
The way TFS (or Azure DevOps) works just leads to massive commits for new features, and when I do these features I'm always touching 200+ files.
Goodness, I've even got outstanding reviews that touch over 1000 files...
Sure I can do these with git too, but that'll at least be due to things getting squashed in a rebase AFTER the review.
Hi Tim, I cannot create a user on your suggestion site. Says "A required field is missing. Please fill out all required fields and try again." even though I filled all fields.
Make sure you select a category. That’s a required selection.
One argument for adding comments to classes and methods is intellisense support. That being said, I'd rather spend the time working on system-level documentation instead. Things like architecture, developer setup, change control processes, CI/CD pipelines, coding standards/practices, local development & testing, etc. I think this higher-level documentation is far more valuable than anything inside source code files. The project I'm on is architected in such a way that it's nearly impossible to test locally. You need to deploy to Azure in order to effectively do any development testing. There's zero documentation how to do local testing, which is bad for any new team members joining.
💯 agreed. Code comments and git commits are fine, but it's the architectural design/deployment/testing documentation that really will let you communicate how the software and the system of making that software and maintaining that software works to other developers.
Hey Tim, good video. Can you try to have a video format where you speak along with some examples from your screen?
I have that. Every Monday a video comes out like that. These videos are actually podcast episodes, so I don't include required visuals.
Wow this is the first time I saw your real face. As always great job delivering new knowledge to us.
Thanks! I'm "visible" every Thursday for this Dev Questions series.
hi Tim, your words are good. but some examples/visuals about how you do it, would really help.
Then the middle management comes in and in comes JIRA, Confluence, PowerPoint. "Let's integrate this, into this, into that so we can get automatic reports. Make sure you get the same notifications on Teams, Slack and Email too"
On a serious note though. Comments in code, processes in Markdown in a wiki, but where do you document UML? Especially sequence diagrams, which are important for microservices cause who knows what goes where. Is there a way of avoiding that?
Document UML? UML is documentation. I'm assuming you mean where do you put UML. In that case, the answer is almost always "I don't". I can't remember the last time I used UML in any serious manner. If code comments are bad because they aren't updated with the code they are right next to, UML is 1000x worse. It can have a place in narrowly-scoped places, but it definitely shouldn't be widespread. I think your example of documenting microservice interactions is probably a good one. In that case, I like to put it right in the Readme document. Keep it as close to the forefront as possible. I also try to keep it as high-level as possible.
Most needs for comments can be avoided by writing readable code. I hope it's not as prevalent now as when I started but developers would put half a screen of comment before a function telling what it did and all the intricacies and then name it 'getd' and have variable names 'a' and 'r' and 'q'. So there was double the amount to read to try to figure out what the code did and a puzzle at the end to decipher which part of the code went to the text.
I believe updating code documentation is just a part of the job, especially if you're in a team environment or know someone else might be there later.
I always document using XAML code comments. I reserve regular comments (i.e., using // or /**/) for those lines of code where an explanation is needed.
But yeah, I always use XAML because it's great when you're consuming your types or consuming someone else's library and can just hover to see the documentation in the IDE.
Otherwise, I believe code should be readable. Unless it's something that's weird, anyone should be able to just open a file and read it top to bottom.
Thanks for sharing!
I use code comments when defining Value Objects, Domain Objects, or interface methods. Every other place should have self documenting code (Good variable naming, Smaller easy to understand functions)
How about Regex filters? Tricky code bits?
@@IAmTimCorey
If we were using them sparingly I would have regular expressions be evident by where it is being used.
bool IsAnEmail(string possibleemail) {
string EmailRegex = “…”;
//Logic to test Email
}
If I was using Regular Expressions frequently, I would wrap it in a ValueObject and add comments.
///
/// The Regex an Email address. Requires and @ and a . to be valid
///
public record EmailRegex()
{
public string Value => "";
}
We would then set up unit tests to make sure that RegEx is valid
If there are parts that are “Tricky” we want to focus on making them not tricky by refactoring the code.
If we can’t refactor, we will look at education so it isn’t tricky.
If improving education doesn’t make the code less tricky, we will add a comment.
@@IAmTimCorey ninety times out of a hundred, you can replace the documentation with well written code. Leave comments for the 10%. Especially when doing something weird.
Good channel few years ago. Now ads and shit.
What ads? I put out two videos every week on development, with over 500 in the back catalog (over 100 from last year alone).