If Code Is Self-Documenting, Why Do Comments Exist?

you can go out there and find probably a hundred articles from very well respected programmers and authors and people that will tell you self-documenting code is a great practice and why you should do it and if you really want to believe that you'll go out there and confirm your bias [Music] you ever join a software project as soon as you get on it some senior programmer or maybe lead developer tells you hey we follow self documenting code here so don't add any comments to your code well today i want to talk to you a little bit about why this has become such a popular practice that a lot of people suggest and why you may reconsider following it even if you've heard this from a lot of programmers because ultimately comments do exist for a reason and they actually can help you a lot more than you realize if you step back for a second and really think about it over 25 years ago when i first went to college to learn to professionally program we added comments to everything and once i got my first job in the industry i joined a team that was writing a lot of c plus code there was a little bit of visual basic a little early java there as well and at least at that first company now again every company is different everybody added comments to their code and so that's just kind of a habit i picked up and i went to a couple other companies after that we added comments to all of our code there too we actually had tools that would make sure that there were comments added to every method now there were cases where we'd make exceptions because this isn't really about following a practice just for the sake of following the practice but we wanted to have documentation available generated from our code that anybody on the team could look at but once i got into consulting this was about 15 years ago i noticed something immediately and that is that all the other co-workers i worked with on consulting engagements never added any comments to their code and i would ask them like hey how come you guys don't comment your code and they would often just say well the client isn't paying for comments they're just paying for functionality and about five years after that i started to see in the industry this popular lie basically of self-documenting code and really the concept behind it just being that if you write your design clean enough if you use variable names that represent the business well enough if your code is simple and you've structured it properly really comments are unnecessary and so i want to talk to you a little bit today about why i actually believe that's something you should be very careful to consider adopting if you want to have a long career because it can actually really make it hard for people to extend and maintain your code and it actually makes your life harder when you have to go back and revisit code you wrote a while ago so why do people love to believe that self-documenting code is a good practice well the first reason and you're not necessarily going to like this but i think if you're really honest with yourself you'll believe it is laziness you've heard this popular trope that a good programmer is a lazy programmer and i'll make a whole video in the future about why i think that's actually not true and it actually fights against your ability to be a good programmer but at the end of the day writing comments takes effort it doesn't happen automatically now there's tools out there that can look at your method signatures and generate comments but there's different types of comments we write right sometimes they're at the top of a public method or a class or some variable but there's also comments that we put in algorithms just to help people with reading the code you've probably heard of this concept of confirmation bias it's basically that we all have things that we wish were true that we've adopted and i think if we're honest with ourselves and and i've fallen prey to this too i want you to know that out there it's not like i didn't ever want self-documenting code to be a really good practice myself but you can go out there and find probably a hundred articles from very well respected programmers and authors and people that will tell you self-documenting code is a great practice and why you should do it and if you really want to believe that you'll go out there and confirm your bias but equally if you go out there and look for articles and information and documentation that says why documenting your code actually is valuable and you should take the time to do it you're going to find just as many articles and as many opinions so ultimately i'm not here to just try to force my opinion on you and say hey you watch this video afterwards you must document all your code i'm just trying to help you think maybe about the other side of the argument if you are someone who really has practiced self-documenting code and wants to keep doing it the second reason people love to believe this self-documenting code principle is they don't like to see the comments in the code when you're reading code having comments there introduces more lines right you're scrolling through the file before you get to the method declaration or as you're reading an algorithm there's now comments littered in there and it does add visual clutter now most ides and vs code can do this they have settings where you can just say collapse comments by default you'll see a little line that'll show you that there's a comment and you can expand it if you want to view it now i know a lot of us like to follow some arbitrary number of well if a file gets to a certain length of lines of code then it's too big and we need to separate it out into separate files and i think that's a good principle but in practice i find i often use there's like a document outline of some sort or a class outline of some sort when you're reading your code you can kind of click on that and jump between members and so if there's comments you can kind of skip over them and navigate anyway the third reason many people like this principle of self-documenting code is they don't want to have to refactor comments along with code if you take the time to add comments to your code well when that code needs to change now the comments need to change and i just personally believe if you're going to be a professional things like unit tests code comments code coverage tools all those things they're built for a reason they're there because they actually do help us do a good job and so i would just say you might want to gut check yourself a little bit and if you're really thinking that the reason why you don't want to write comments is because it's extra work and you have to refactor them that's not really a reason not to do it that's just a reason why you don't want to put the effort in at least be honest with yourself about it the fourth big reason many of us love this principle of self-documenting code is because honestly we think our code is easier to read than it is if i get a task assigned to me to write some code often i have to talk to the product owner or i have to read requirements to understand what's that code gotta do and i may understand a whole bunch of terminology in the requirements that's related to that business let's say it's in you know auto manufacturing and i'm creating some feature that has something to do with testing like the pressure of tires when they're installed on the vehicle i'm gonna have to understand all these business terms that are specific to tires and specific to pressure tests and so i'm going to write hopefully my code and use a lot of variable names a lot of method names that match the business domain but when somebody else comes along to read our code if those variable names introduce anything different or anything they've never been exposed to now they have to read the code and if you don't have any comments in there it's going to be really hard for them to understand what you did and why you did it and why you designed the code the way you did unless they go all the way back to the requirements or they have a discussion with you so i'm not here just to bash self-documenting code again it's up to you if you want to follow that principle or not but let me just share a couple really valuable benefits to commenting and if you're not doing it on your project you're missing out from all this the first thing comments do if they're applied properly is it's going to help people understand the code quicker hey if every time people want to understand code they got to go into that method and read all the source code that takes a lot longer than if you take the time to just write some good comments and if you've written anything that's an api that's used by the rest of your team let's say it's even just a helper class with a few methods or you know a couple classes that have relationships to each other but they're used everywhere having your development team have to go through all the code and read that just to understand what it does is really putting a much bigger burden on them than if you just take the time to think about how can i describe what this code does and what each of these methods do and let that be the only information they need to know to use the code the second thing that's really valuable about comments is it lets you map your codes terminology the names you've chosen to the business domain this goes back to the point i was talking about earlier but if you know something about a business problem that you're solving sure we all do the best job we can hopefully we've read domain driven design and we're trying to come up with names for our classes and our identifiers and our symbols that map in some way to the business domain but many of us find we have to introduce new concepts into the code to make it dry or reusable and sometimes there's no mapping between that term that you sort of invented in your code to represent a concept and something in the business domain and so the only way you're going to let somebody quickly understand that without having to read all the code and understand all the behavior is if you take the time to think how can i write comments that explain this concept and really hammer home how they got to use this code so that they don't have to go through and read everything in my design the third big benefit to comments is it lets the developers on your team use the tools that they have and all the features of those tools to call your apis when most text editors first come out they don't have intellisense or autocomplete when you're writing code and eventually they add that feature you can hit the period character or some other character that indicates that you're about to invoke a method or access a property or something like that and eventually they'll add support for comments and that's always really appreciated by the industry if you go look at vs code for example it has really rich ability for you to view not just the types of parameters you're going to pass to a method when you call it but if you put code examples in there if you put error conditions all that information surfaced instantly to the person who's about to call that method without them having to go find the class open it up have it side by side or you know use multiple monitors and now they've got to look at the code they're writing plus read your code let them use the tools they've already got if you don't take the time to add comments to your code you're really missing out on everything your editor or your ide of choice has to offer the fourth big benefit to writing comments in your code is it encourages you to surface behavior in the comment again if you have an error let's say that's thrown in some condition in your code you have a couple decisions to make you could either just throw that error and have a unit test and hope the developers are reading the output of the unit tests you could create some object that's returned that has a error type property now they have to understand a whole another contract for a response type they have to read all the documentation if you wrote it for that or they have to read all the code for that or if it's a simple type of error in a certain condition you can put that right in the comment for that parameter and talk about the behavior and you can also describe depending on the state of the parameters that you pass in how that method might behave differently they might have to read a hundred lines of code split across six different methods in three different files just to understand the behavior of something that you can tell the rest of the developers and people calling your api ahead of time if you just take the time to put it in the comments the fifth thing that's really great about adding comments to your code if you're not doing it today is a lot of tools that will generate documentation from code things like ts doc or js doc or doc fx if you're using c-sharp almost every language has some way of generating documentation rubydoc is many of them allow you to also add markdown files or just other separate files from your code that let you describe let's say a collection of classes within a namespace or something like that they also let you add separate whole topics with examples basically they give you all these really rich ways to add documentation to your code above and beyond just the comments for the code itself that makes it easier for people to understand it in the sixth reason and i think this is one of the most important for using comments is it really encourages you to treat your code like a product many times i work with other developers and they're frustrated because they can't read somebody else's code and then they go on to write their own code and they shortcut their unit tests and they don't add comments and they're basically doing the same thing that the person they just complained about did but if you really want to reduce the amount of time it takes to understand code if you want to make it faster to refactor if you want to be able to onboard people quicker if you want to be able to go into code you wrote six months ago and not spend a day trying to wrap your head around what that code does consider having the discipline to just take the hit and take the time and add comments to your code so what do you think about self-documenting code and whether there's any value in comments or if there's really good reasons to add comments or to skip them leave me some comments below until next time thanks [Music] [Music] you

Channel: Thriving Technologist

Views: 54,685

Keywords: self-documenting code vs comments, self-documenting code, source code comments, programming comments best practices, programming comments, documenting code best practices, self-documenting, source code documentation, source code, documenting, code comments, comments, commenting code, programming, programmer, software development, software developer, software engineering, software engineer, software development team, programming best practices, software, development, developer, code

Id: 1NEa-OcsTow

Length: 14min 22sec (862 seconds)

Published: Wed Aug 03 2022