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

Рет қаралды 54,125

Күн бұрын

As programmers, we often follow practices because of hidden desires - and "self-documenting code" is chief among them. In this episode I'd like to share some of the tradeoffs and implications of choosing to add comments to your code or not, to help you make the best decision for your software development career.
When I first started developing software 25 years ago, the company I worked at mostly used C++ with a little Visual Basic and Java. At that time, all the other software engineers I worked with added comments to their code. And at the next two software product companies I worked for, programmers also chose to add source code comments as a regular practice.
But once I moved to Austin, Texas 15 years ago and got my first job as an IT consultant I noticed something interesting. None of the other programmers on my team added ANY comments to their code! When I asked them about this, they would often say "the client is paying for features, not comments". I didn't find this a very acceptable reason for not adding comments to code, but I did my best to play along.
Around this time the popular programming practice of "self-documenting code" first showed up on my radar. The idea being if we write our code with a clear enough intent, but using business terms and clean designs for the software we write, comments are unnecessary. But upon closer inspection I found this to be (in my opinion) wishful thinking rooted in laziness, upon a host of other factors.
I hope this episode helps you make an informed decision about whether the benefits of code comments are worth writing them, or whether you should continue to practice self-documenting code as a principle. I believe we can have the best of both worlds: well-written code that reflects the business domain and is simpler to read, but with accompanying comments to reduce the time it takes for our software development team to use the APIs, helper classes, and other functionality our code and libraries provide.
#programming #coding #softwaredeveloper
RELATED CONTENT
How Senior Programmers ACTUALLY Write Code
• How Senior Programmers...
Need help with your career? Book a free career consultation:
jaymeedwards.com/services/sof...
CHAPTER MARKERS
00:00 Introduction
02:50 Why Practice "Self-Documenting" Code?
02:56 #1 Laziness
04:43 #2 Reduce Visual Clutter
05:43 #3 Refactoring Burden
06:39 #4 Overconfidence in Simplicity
07:56 6 Benefits to Commenting
08:03 #1 Reduce Comprehension Effort
08:50 #2 Accelerate Business Understanding
09:50 #3 Use Comment Features in Editor
11:03 #4 Surface Code Behavior
12:07 #5 Additional Documentation Opportunities
12:48 #6 Treat Code Like a Product
13:51 Episode Groove
Download a free software development career guide from my home page:
jaymeedwards.com

Пікірлер: 1 000

@HealthyDev Жыл бұрын

Do you find any value in comments? Are you honest with yourself about why you don't write them? I hope this video helps you not "throw the baby out with the bathwater" with respect to commenting code! ►► Know your options! Access my FREE data hub for the top 25 software industry roles, TechRolepedia → jaymeedwards.com/access-techrolepedia/

@nickjanke227 Жыл бұрын

What about job security! The more complex and the less comments == you can't let me go! 🤪🕶

@ericpmoss Жыл бұрын

Your thoughts on overconfidence in one’s own clarity are spot on. I had to learn, with no assistance, a code base of 40k lines of Common Lisp that had no comments. What a disaster. I did it, and to spare anyone else that misery after I left, every module, every file, every function and variable got comments explaining why it was there. I revisited the code and comments regularly, and even 10 years later I am happy with it, but have zero issue with revisiting again to hone away cruft.

@-----0----- Жыл бұрын

Thank you for the video! I've been trying explain all of this whole my career and it was never successful. Now I have your video so may be it will help me in the future explanations :) Yes, I use it mainly for Requirements Traceability (JIRA ID + Summary), explain not obvious moments, explain concepts, leave links to wiki if for that part diagrams or more expanded explanation exists, leave links to valuable docs, put examples with real values (especially when it comes to complex algorithms). Unfortunately what I see from project to project, people avoid writing any comments like crazy and then waste time again and again and again trying to understand related requirements, find related docs or get the concept. And when people rotation is crazy this problem becomes just huge. Business just wastes so much money because of that and nobody cares :) IMO, self-documenting code principle made more harm to software world then good. Idea behind that is not that bad but to follow it is hard and most developers do not do that and still it does not mean comments are not needed at all. Unfortunately, the only thing developer takes from the whole principle is that from now on he should not write comments and he will be considered as cool developer :) P.S. I found that for projects which have low resources availability even simplest possible Requirements Traceability (like just keeping link in code to JIRA and have in that JIRA all related requirements) works fine.

@-----0----- Жыл бұрын

P.S. Again for low resources availability projects which already have not very good code: just adding an @Aspect which has mapping to requirements, explanation of concept, design, wiki links, etc and then marking related code with it boosts development performance. Let's imagine there are 4 levels of code improvements: Level 1: Have Aspect annotation, mark related code with it Gives minimal quality level, is very cheap and is first step to next improvements. Level 2: If you've got additional resources you may go with this one. Do not just mix every new aspect with help of "if"s (unfortunately it's widely used practice). Create extensions and keep them as inner classes. It's a little bit more complex than level 1. Having level 1 done makes it easier to make such extension because the code is already marked and developer only needs to extract it into inner classes. Level 3: If you've got additional resources you may go with this one. Extract those inner classes into separate ones (if it is not mandatory to keep them as inner). Having Level 2 done it's much easier now. Level 4: If you've got additional resources you may go with this one. Group aspect related code into separate modules. Having Level 3 done it's much easier now.

@helicalius Жыл бұрын

The Cons to Commenting overweight the Pros.

@sh0ckwave68 Жыл бұрын

I was hired by a company a while ago to to pick up where another contract developer had blazed the trail and I was blown away by the amount of comments he had created for anyone, like me, who might have had to continue where he had left off. The detail he provided was truly a game changer and saved me countless hours of trying to get a grip on what he was trying to accomplish. I vividly remember the day I walked over to his desk to thank him for making it so easy for me to understand what he had created and his reply will forever be etched in my memory. He said, "I comment my code as if the people I hand it off to have my home address and are armed with pitchforks and torches."

@Humanrebel 4 ай бұрын

Better write the code with that attitude.

@jp-gy3vh 2 ай бұрын

Good guy. I try to do the same

@jmwild1 Жыл бұрын

Comments for me were always for the "why" not the "what" or "how". So self-documenting code works until the "why" isn't clear.

@sealsharp Жыл бұрын

That is simple and clear. Love it.

@SerenityDreaming Жыл бұрын

Love this.

@Mirroar Жыл бұрын

Agreed. It's kind of the same with commit messages that should indicate why something was changed instead of how.

@TrackedHiker Жыл бұрын

@@Mirroar I disagree about commit comments. To me, commit comments have one purpose they MUST fully serve, and any other use is incidental or a bonus: they must aid in locating which commit broke prod. And they must do this for a developer not on the team who wrote the code, at 2 A.M. on a Saturday morning, when that developer is sick or mildly intoxicated. To me, explaining why is right out. I’d agree that explaining how is out, too. What must be explained is what was changed, to express the part of the system touched, the type of change being made, to quickly rule in or out each commit as potentially the source of the breakage.

@MrAntice Жыл бұрын

@@TrackedHiker I have a question for you then. Since I'm not all that old in the game. I use file: change as a commit pattern for my commits. sometimes with a note if the module I'm working on is in a healthy state or not. Would you consider that a good style?

@Wedgylord Жыл бұрын

Getting into a project that is "self documented" was rather hard. It felt a lot like reverse engineering.

@WarrenPostma Жыл бұрын

Every single person who I have worked with who preached "self documenting code" was a confirmation bias victim. No amount of experience with the detrimental effects of their ideas ever cracks into that kind of developer's head. They do not permit questions and doubts to ever trouble their outward calm. If you violate the "don't talk about the elephants" rule, you will get canned, if it's in their power to can you.

@ubaidarshad Жыл бұрын

exactly

@Klayperson Жыл бұрын

when i went to change something about the way my suckless dmenu worked, i was interested in seeing what their "self documenting" C code looks like. surely being C, being self-documenting, and being *suckless* means it's beautiful, readable non-sucky code, i thought. no, their self-documenting C code was just regular spaghetti C code, with all the bad habits of C programmers who use abbreviations for identifiers and don't make anything clear at all. to have any idea about what was going on, i had to hold the call stack in my head. i only got part of my feature working, and had to give up just to have a working dmenu. i'm actually considering writing my own replacement for dmenu instead of getting to know suckless dmenu any better...

@pablofernandogonzalezolmos8472 Жыл бұрын

@@Klayperson "who use abbreviations for identifiers" They wheren't using self-documenting at all. One of the core steps for self-documenting is "use explicit variables names".

@lua-nya Жыл бұрын

@@pablofernandogonzalezolmos8472 Perhaps. But the sheer amount of people who claim their project is self documenting without it following proper principles is great.

@pedrojtmartins Жыл бұрын

The way I see it, if you need comments to explain WHAT your code does then you should probably refactor it. (E.g. Create focused/smaller functions). On the other hand, explaining WHY you''re doing something can be quite useful when it is not clear enough on its own.

@nemostein1676 Жыл бұрын

I really like this point-of-view about "What" vs "Why"... I understand that "What" must be implied by naming, while "Why" should be declared as comments.

@sergeliatko Жыл бұрын

Totally agree about the WHY thing

@ChristianConrad Жыл бұрын

It's hard, at the time, to know exactly what it is that will need to be explained to others or your later self. While you're in the middle of it, stuff feels obvious.

@abit_gray Жыл бұрын

The WHY part is very important - I hate finding comments without meaning. The best ones are just translations to/from English (to local language we usually speak). You need the intend especially when you find out removing a condition (or something) can fix a bug - but can you remove it? It can burn so much time when you cannot "just risk it".

@SerenityDreaming Жыл бұрын

Boom. Yes. Anything that can't be made obvious up front without sacrificing hygiene can be a comment. Right?

@lucasdolsan1636 Жыл бұрын

I wouldn't say self documenting shoudn't be made, making the code as clear as it can be, as expressive as it can be so it is instantly obvious what everything is doing and how it is doing is a must. But that doesn't mean you shouldn't have comments explaining all sorts of stuff, especially WHY the code is there, and not WHAT it does -- what the code does should be as clear as possible, and that's where I see self documenting code being the most useful. And obviously that doesn't exclude all other types of documentation that are outside of the code base itself, like diagrams and what not.

@AramisWyler Жыл бұрын

Indeed, if you're having to spend a lot of time putting in comments (outside page or section headers) then the code your writing is probably overly succinct and unclear, and should simply be written better.

@Ziggity Жыл бұрын

Came here to comment this precisely. Really in my company we do both.

@BulbasaurLeaves Жыл бұрын

I agree. Self documenting code reduces the need for "deodorant comments" (comments that cover poorly written, unreadable code). It doesn't mean you won't need any comments in your code.

@epiicSpooky Жыл бұрын

100% - the code should self - document the what and how, but why is even more important and not really possible to express without comments. (So often in code review I ask for comments explaining why even though I personally know why)

@Hathwos Жыл бұрын

This. 👍🏻

@carldaniel6510 Жыл бұрын

I've been a professional developer for more than 40 years and have worked in teams ranging in size from 1 to 25 or so. I've found that over the years I've commented less and less, but I'm far more intentional with my comments than I was as a new developer. I try to write code that's as clear as possible on its own, but then add comments to explain WHY - particularly when I find that I have to add some code that "shouldn't need to be there", but is in fact needed due to some not so obvious cause. I'm the primary user of my own code - I'm using (and maintaining) classes and methods that I wrote 20 years ago on an almost daily basis, so I appreciate the effects of having put useful comments into the code back when it was clear in my head.

@alexeycherkashin6251 Жыл бұрын

I think the biggest gap of the "no comments" approach is how real engineers execute it on actual projects. On one of my previous jobs I had a task to optimize an endpoint. The code there was verbose enough to understand what it does. However, because of the verbosity, all extra temporary variables and steps, it had poor performance. Instead of doing all business logic inside one loop, there were numerous loops. I can't recall numbers exactly but it was something like 9*N instead of just N. And that cost us huge performance hit. The business suffered a lot. I changed it to N time complexity. However, as you might guess, it became a little bit less readable in comparison to what it was. To compensate for what I did, I've added some comments. But on PR review I learned our company has a "no comments" approach. How did I know it? I was asked to REMOVE JUST COMMENTS. Not rewrite my code to make it more clear, not even move comments to a commit message. No. Just remove them. When I asked why, I received the answer: just for the sake of consistency. I understand when we agree about a set of rules to make our lives good. But I think the difference between an engineer and a good engineer is that a good engineer understands when it's time to break some rule in order to make our lives even better. Like, there are exceptions.

@HealthyDev Жыл бұрын

Great story! Thanks for sharing.

@rdean150 Жыл бұрын

Removing comments for the sake of "consistency" is a jaw-dropping request. Especially considering that you made the honest, good-citizen admission that your change was sacrificing readability (and hence future supportability) for performance. Adding comments was literally the ballast that offset the potential downsides and made your change a clear win. In those situations, I would hope that you did not squash merge, and your comments could still be found in the commit history if future engineers really needed them. A slim chance is better than no chance.

@genechristiansomoza4931 Жыл бұрын

If they don't want comments, you can break it down into several private methods with meaningful name. You can pass params by ref if needed.

@TrackedHiker Жыл бұрын

I’d love a chance to dig into this idea that you couldn’t improve the performance without making the code harder to understand. Totally agreeing that some algorithms are much harder to understand than others, even difficult algorithms can be written well so they are much easier to understand.

@alexeycherkashin6251 Жыл бұрын

@@genechristiansomoza4931 agree, that's a possible approach. There are some other ways to make code readable. At the same point, my original comment was more about how others apply this "no comments" technique. If people don't fully understand it, they tend to just blindly follow the rule and that's it.

@MarcinWanago Жыл бұрын

Hi, Jayme. You've raised an important subject for sure. For me, writing self-documenting code does not mean putting less effort into it - quite the contrary, in fact. I do the following: 1. I try to write code that's easy enough to understand immediately. This means choosing the right variable and method names, or maybe declaring additional variables and methods that better illustrate my thought process. I almost never use abbreviations and write long and descriptive names. 2. If I feel like writing a comment, I go back to step 1 and think if I can write the code more descrpitively. 3. If I can't write it in a simpler way, I definitely put a comment that describes what's going on. For me, writing "self-documenting code" most definitely does not mean not writing comments. It just means spending more time on steps 1 and 2 from the above list. Cheers!

@JanPavlikdr Жыл бұрын

Absolutely agreed!

@williamshipley4841 Жыл бұрын

It's certainly possible to write code so that you can understand it. Look at it again in 5 years and see if you still think so when you have to make a change.

@nitePhyyre Жыл бұрын

@@williamshipley4841 That's what code reviews are for.

@williamshipley4841 Жыл бұрын

@@nitePhyyre aren't you then relying on verbal comments? Will they be there in 5 years?

@nitePhyyre Жыл бұрын

@@williamshipley4841 No. Sorry for not being clear. What I meant to say is that you don't have to wait 5 years to see if the code is easily understandable. You should find out the same week during code review. If the reviewer doesn't easily understand your code, you didn't do a good job of self documentation. If they can't understand it, then it should be sent back to you for refactoring to make it more easily understood.

@aDifferentJT Жыл бұрын

Kevlin Henney said "A common fallacy is to assume authors of incomprehensible code will be able to express themselves clearly in comments." Documenting, either with comments or out of code docs, API boundaries is definitely very useful, but within a module it can allow people to excuse bad code, I have never seen comments so good that I can work on a module without fully reading and understanding the code itself, where documentation is useful is when I want to use something without fully understanding it. The only real case when I would add comments within a module is if I am solving the problem in a non-obvious way for some non-obvious reason, or there is some change that should happen but cannot yet. // This function can be replaced with the one from library X when the new version of that library is deployed

@_Dumb_Answers Жыл бұрын

I think the optimal practice is to use meaningful code when you can, and use comments to supplement when needed.

@tarsierontherun Жыл бұрын

The thing is, you don't actually know if you need it.

@leeow3n Жыл бұрын

yeah this video really failed to be reasonable, and fell into typical binary this or that thinking.

@homelessrobot 8 ай бұрын

@@tarsierontherun well then do it always if thats when its needed.

@nefthy 8 ай бұрын

If you don't have anything usefull to add beyond, what the code already states, please feel free not to comment :D

@viktorlernt6063 7 ай бұрын

Agree 💯

@AlexanderGuitarguy Жыл бұрын

Unfortunately, you were right saying that developers do not invest their time into comment refactoring, which leads to situations when comments are absolutely misleading and they do harm to the rest of the development team. However, zero tolerance to comments in the code is also rather dumb as real enterprise programming requires some "magic" to be explained, unlike in the books about software design and clean code.

@WarrenPostma Жыл бұрын

Yep. Delete the old ones. If you want the old docs back, go look in git diffs. Write //TODO: Document FooManager v3 API surface, see JIRA xxxxx.

@JanPavlikdr Жыл бұрын

Well, this os exactly why I try to have “self-documented code”, which is actually really wrong term to me - I just like to use things to be more expressive possible. But yes, right comment on right place is life saver.

@MrAntice Жыл бұрын

@@JanPavlikdr Expressive code is great. especially if paired with at least some comments explaining what is done, or at least a reference to any standards or patterns employed if they aren't very common. For business logic, if the code is there because of some rule that has to be followed, then a comment stating that, with a link to a list of rules you have to comply with is also very good.

@jimiscott Жыл бұрын

As good as the books on this subject are, the examples tend to be trivial, or easily expressible. I feel that once you start bumping up against other APIs or having to refactor because of perf, you code tends to become a bit more terse and/or harder to read. In these cases it should be common sense to add some comments, just to explain the scenario and/or the rationale for having the code as it is.

@Fafix666 Жыл бұрын

If you require that "magic" to write something, then there's a much deeper problem - badly designed code. In the recent 4-5 years, since I've become much more familiar with SOLID and clean code in general, I've only had to "hack" something once. And it was still well designed and very clear to understand for 99% of cases.

@smbarbour Жыл бұрын

I have personally been bitten by not commenting my own code. What makes perfect sense to you when you write the code can absolutely look like the ravings of a madman several months or years down the road when you look at it again, and you're left scratching your head thinking "What the heck was I thinking when I wrote this?!" Obviously, not every line of code needs comments (i.e. variable declarations or iterators), but any time you do something non-trivial, throw a comment in there. If you revisit it later, and the code still seems obvious, then maybe you can consider removing the comment, or ask a peer if the code seems obvious to them.

@TravisHi_YT Жыл бұрын

Yep, I was almost bitten by some of my old code, fortunately it was commented nicely so I avoided wasting time trying to re-figure it out.

@rdean150 Жыл бұрын

I can't tell you how many times I've thanked my past self for documenting his code. Sometimes I appreciate his hard work so much, I buy us a round of beers. And I enjoy them both.

@jp-gy3vh 2 ай бұрын

Precisely this

@skurke Жыл бұрын

For me I like writing comments for things that don't make logical sense, but need to be included for some weird dependency from an external service or something like that. Second, I like to write comments before I code and then write my code to make the comments unnecessary

@ericpmoss Жыл бұрын

Yes - IMO comments are for surprising behavior, and when it’s faster to understand with the comment than without. It’s a balancing act.

@WarrenPostma Жыл бұрын

Violations of the Principle of Least Amazement. That's what I tell people comments are for. Say WHAT? Okay, document.

@SmallSpoonBrigade Жыл бұрын

@@WarrenPostma There's that, but there's also information about what the code needs to accomplish. Just because you've got some sort of a return value doesn't mean that you're not going to want more information coming back to the code later on without remembering why and what you were doing.

@drescherjm Жыл бұрын

@@ericpmoss That is where I like to put comments the most. For example, if a line of my c++ code looks like it can be removed but is necessary for some unexpected reason I comment so that in 8 months when I am stepping through the code (and have forgot what I was thinking when I wrote the code) I don't remove or refactor the line and create an unexpected bug in the process..

@jamesfaucher4588 Жыл бұрын

Also when I'm writing comments, I'll take a step back and ask if this is better as a standalone function, allowing for good function names. If you're trying to understand the overall logic of a function, it would be nice not to have errant logic that doesn't contribute significantly to the main logic mixed in.

@Bboytraxx Жыл бұрын

The introduction of the video summed it up perfectly. When you worked within the company, you created documentation and when you became a contractor, you didn’t. It’s not in the best interest of contractors to have well documented code.

@BrianKapellusch Жыл бұрын

I'm a self-documenting code advocate, but I'm referring to mainly when people write gnarly conditional statements and document them instead of just extracting that conditional statement to a private method and naming it well. Those situations are the ones where I see unnecessary comments more often than not. Comments are certainly appropriate for things like design choices, headers of public methods, etc.

@KiddyCut Жыл бұрын

Completely agree. If I have a code block and comment it with //set bank Details i could just have the helper method doing that with a good name. But id still document publically callable methods

@Fafix666 Жыл бұрын

Comments are especially useful when writing public libraries, nuget packages etc. As long as you can't easily access the code, comments are a godsent imo. But it's a rather niche use case imo.

@defeqel6537 Жыл бұрын

@@KiddyCut especially when you have multiple of those type of comments, you never really know whether the subsequent commented sections are part of the previous section or part of the overarching function(/-ality)

@phildem414 Жыл бұрын

No comments policy, sush a falacy 😤. Concise and usefull comments are a skill if not an art !

@Caledoriv Жыл бұрын

I'd like to add another reason why writing comments is helpful - especially in complex and complicated algorithms: You are forced to explain (i.e. write down) your thoughts. This means you have to organise them first and summarize them such that your code still is "nice" and "readable" with the comments. My emphasis here lies on the "organise" your thoughts point: I don't know how often I've asked fellow colleagues to look at my code and help me identify why / where a specific behaviour is caused. For this, I explain to them loudly what I do in the code - and then realise the mistake myself even before speaking it out loud. I'm pretty sure this has happened to everyone here already.

@sealsharp Жыл бұрын

I like practices like this a lot.

@manishm9478 Жыл бұрын

Rubber duck debugging hehe

@markt1964 Жыл бұрын

I would argue that if you have to explain your code then it isn't cleanly written in the first place. This is why code reviews are important.

@fredericbrown8871 Жыл бұрын

@@markt1964 My understanding is that they're still writing/debugging that piece of code and that during the process of explaining what they're doing to others they are able to understand what they're doing wrong. Presumably their code isn't streamlined at that point, but that said, a very well written, clean, easy to understand, code can be correct or defective depending on what it is expected to do.

@coffeemusiccoding Жыл бұрын

Ah man, when I was a junior I was dropped into projects cold a couple of times with "self documenting code". The developers were very good developers but readability was almost impossible. Needed them to walk me through it each time. However I remember the most experienced developer in my company had a mixture of good naming and good comments, I never had to bother him once to get him to walk me through it.

@MikkoRantalainen Жыл бұрын

If a piece of code requires that other team members have to ask about it, it's definitely not self documenting code. It doesn't matter if it contains comments or not. My guideline after writing software for living for a couple of decades is that if a team member has to ask about any piece of code, that code should be rewritten to be more understandable, or if that's not possible then you have to add enough comments or other documentation. Only bad coders have to write code that requires team members to ask about it and in that case that's done because of job security, not because it would actually result in better code.

@xybersurfer Жыл бұрын

@@MikkoRantalainen i mostly agree. but being asked about code, could also be due to them not understanding a fundamental principal. for example: not knowing the syntax to create their own class. i've met someone that didn't know this, after decades of programming

@MikkoRantalainen Жыл бұрын

@@xybersurfer I totally understand that sometimes a co-worker may have holes in their knowledge of the programming language and I think a good answer to such question consists of two parts: (1) explanation to the actual problem, and (2) tips about how to figure the same thing in the future; that part could be the official language reference/spec, some google kung fu* technique or a good book about the language. (*Some say that proper form is Google-fu: "Google-Fu" is merely being able to find things quickly and easily, particularly difficult things, on Google. And the "-fu" comes from "Kung Fu"; the "google-fu" phrase is sort of an outgrowing of the whole usage of "ninja" to mean "someone who is hyper-competent".)

@soppaism Жыл бұрын

Perfectly self-documenting code can still be hard to map back to requirement documentation. Allowing yourself a limited amount of well-thought-out "tactical" comments is probably more likely to reduce cost than increase it.

@googleiscreepynanya5926 Жыл бұрын

Indeed. I like readable code with an occasional comment to specify intention or clarify what it does when it makes sense.

@BaillehachePascal Жыл бұрын

When I try to explain why I give so much importance to commenting my code, one important point is that it helps me a lot when I'm coding. You know the quote 'you haven't understood it if you can't explain it to a child' attributed to Einstein, or the Feynman technique which basically says the same ? This is the same principle I apply with comments when coding: I first explain through the comments to an imaginary reader what the piece of code is doing. By explaining it, I actually ensure that I've understood what it is supposed to do. Then, once I've cleared up my mind with these explanations, I'm ready to translate the comments in natural language to the code in whatever programming language I'm using. In the end the comments stay there with the code for the next programmer, to avoid the burden of the inverse translation (code->natural language) when trying to understand the code, cause I can't believe anyone think in programming language. We are humans, we think in the languages we speak.

@tldw8354 Жыл бұрын

thats a cool idea. I'll try that. sounds logical to me. I have kind of a similar aproach, but yours goes even more way back to re-think: What am I actually gonna do to solve the task and is this approach really usefull and do I really understand the task?

@KANJICODER Жыл бұрын

I find for very specific problem domains that when I explain things succinctly I get told "I had no idea what he was talking about" and when I try to explain things in detail I get told , "He should have shortened his pitch". But yeah, comments help you know that you actually understand what you wrote, because you are forced to explain it. Like "rubber duck coding". Also, this Mortimer Adler quote: The person who says he knows what he thinks but cannot express it usually does not know what he thinks. MORTIMER ADLER, Philosopher Which I found on this video : kzfaq.info/get/bejne/jJOFqbZ8yp7Oh2g.htmlm15s

@mikewright2858 Жыл бұрын

I do the same thing. They are much as for me as they are for the person ten years from now. In my experience, the "hero" programmers like this self-documenting garbage, as they think their time is just so valuable that they shouldn't be bothered, and if you can't keep up, then you're simply not worthy. I'll manage those people out the door.

@defeqel6537 Жыл бұрын

@@mikewright2858 self-documenting code generally takes longer to produce than a comment. This is why you need peer review, so people can actually say "I have no idea what the code is doing here"

@user-uu3us9ys4q Жыл бұрын

I also find it an easy way to plan your work: write in comments what you gonna do here, then piece to piece code it under each comment line.

@robinterrycomposer103 Жыл бұрын

I could not agree more with your statement about making your code a "product". Software engineers don't often realize how much the code they work on is worth to the company - it could be literally worth millions. So it's our duty as employees of that company to treat those extremely valuable assets with the greatest care, which includes making sure it's efficient, reliable, tidy and understandable to others. I always understood "self-documenting code" as being code that didn't require hefty user manuals (which are out of date before they are completed, of course) to allow someone with reasonably good software skills to read the code and understand how it works. Comments are part of that, so I never agreed with "no comments" rules.

@slashpl8800 Жыл бұрын

I use comments quite rarely, when I can't describe what exactly happens through names and unit tests. If the code is less readable than I think, someone usually lets me know during code review.

@vincenthernandez1646 Жыл бұрын

+1. Being honest in providing and receiving code review feedback on clarity helps mitigate the effects of internalized confirmation bias mentioned in the video.

@AndreaTani Жыл бұрын

One MAJOR flaw about self documenting code is that the intent behind certain decisions can't be inferred by simply looking at the code. Of course comments like "//declare a variable which contains the total amount" before the line "decimal totalAmount;" are pointless. Outstanding video

@miloszivkovic6256 Жыл бұрын

Understanding code is a skill every developer needs to learn, code will tell you what it does but it will not tell you why. What I find as a developer is that sometimes I add comments when code does something unexpected. A good practice when documenting why something is happening in code is to put a ticket number (if it exists) that relates to that change so that someone reading your code can read Jira ticket that produced that change, it can even be a story ticket that explains the whole feature from the begining.

@GrandpaRanOverRudolf Жыл бұрын

i think that was the purpose of git linking commit descriptions with ticket numbers, but this stays in the version control tool metadata

@-----0----- Жыл бұрын

@@GrandpaRanOverRudolf 1).Commits are verbose and it's often hard or even impossible to extract something meaningful from them. 2).When you need requirements related to a part of code. Let's say you use annotation feature of Intellij IDEA which shows just last commit which in turn may be totally useless from business perspective as it may be related to some let's say refactoring. 3).Developers usually do not care too much about commit message quality :) As result try to gather relevant requirements related to module, class, method, line becomes very slow and unreliable task. If take into account that developer reads hundreds, thousands, or even tens of thousands lines of code per day all the above decreases development performance a lot and additionally makes it more error prone and of course makes developer less motivated which in turn makes his work even more error prone. Having only relevant links in comment speeds that up like a lot and decreases chance that due to verbosity developer missed something.

@HrHaakon Жыл бұрын

This is great until someone deletes older Jira tickets. Guess how I know this pain.

@maxlutz3674 Жыл бұрын

@@HrHaakon Frankly, I would not like to be bothered to hunt down information about code I want to use in Jira when it can be right there in the code. That is a waste of my time. I consider writing comments where appropriate as a professional courtesy and increase of efficiency.

@aikafuwa7177 Жыл бұрын

No amount of self documenting code is ever going to explain or document the implicit assumptions, the pre-existing pre-requisites, or the framework that it is utilizing or meant to fit into. There are larger processes, bigger picture issues, that self documenting code will never be adequate to explain. Just imagine implementing a device driver for a specific hardware family, what is self documenting code going to say about the implicit interaction between two register settings that is done in the hardware? Or the timing requirements between sets and reads or memory mapped locations for a FPGA loaded with a certain revision version?

@YamianGodlike Жыл бұрын

I don't code often, but why not use both? You can always use clear name for your classes, methods, variables and whatnot, AND adding comments for some "creative solutions" (read: ugly hacks that somehow work). You cannot rely on "self-documentation". Even if no one else touches your code, reading it couple of months/years later might not be easy, especially when you had "a brilliant idea" back then and now you have no idea what the hell is going on. And you also shouldn't clog your code with comments, no one will read a giant wall of text, nor should you comment every line of code.

@HealthyDev Жыл бұрын

That’s absolutely what I suggest. I hope I didn’t come across here like I’m saying good design and naming isn’t important. I’m mostly challenging people who may have learned the self-documenting code principle from someone else and takes it to mean there’s no value in comments! Hope that makes sense. 👍

@defeqel6537 Жыл бұрын

@Healthy Software Developer While I absolutely agree that both are needed, the good thing about a "no comments" rule is that it (hopefully) forces people to actually make the code readable and refactor with impunity, and not just rename a couple of variables and methods (even though it helps, it is often not enough). Problems emerge when their automated tests are testing implementation details and hinder proper refactoring.

@adtc Жыл бұрын

@@defeqel6537 I think the rule should be "minimal comments". Use comments to explain what's not obvious and/or why you're doing something.

@fyfoh Жыл бұрын

Been there as a junior dev joining a project only to find absolutely no comments anywhere and be told by the senior developer that the code was self documenting. So it takes me way too long to figure out what's going on, and I get blamed for needing more prep time. :/

@theeox Жыл бұрын

I think both play a huge part in a successful program. Making your code readable is great for understanding it long term but adding comments also allows you to add to what isn't said within your terms. So using both is beneficial for longevity.

@markuspfeifer8473 Жыл бұрын

There’s a difference between comments and documentation. Documentation is the stuff that is heavily supported by IDEs a d other tools, and you should definitely do this for your public methods when writing a library. Comments are the clutter you add to internal and private code, and I view those as a warning sign that the next section is probably difficult to understand, and usually that’s because the design is flawed. Sometimes though, things are just intrinsically difficult, and then a comment can be a welcome aid. However, adding comments should be more of a last resort kind of thing, after you tried refactoring.

@icns01 Жыл бұрын

Well I just finished watching the entire video.....including all his guitar strumming snippets This is one of best videos I have seen for commenting one's code. It is so compelling, in a calm, persuasive manner, that I honestly don't know how any rational mind can argue with it.. Well done and much appreciated!👏👍👍

@mjs3188 Жыл бұрын

Like most things in our field, the original idea has been misconstrued and oversimplified to the extent the point was lost and people just follow it like a religion. See also: DRY, YAGNI, Agile, etc. I've seen javadoc like this: "@param widgetName - the name of the widget" That is useless cruft someone put in because they were told "write your javadoc." It adds no value versus the descriptive variable name. Another one I see fairly frequently in old code-bases is "// 's' is the name of the widget" Just name the variable widgetName instead of using a single letter like we're still writing code out on cards and can only use 6 characters for a variable. That is what self-documenting code is supposed to be. This frees up comments to represent more important things, like the Why, and helps them jump out at the reader as something of note.

@benmathews533 Жыл бұрын

I've seen folks use comments as a crutch for bad names then their comments look like clues in that game where movie plots are described poorly. My take is to write code in a self-documenting style and use comments to fill in the inevitable gaps. Thanks for another great video.

@Replayer-Realm 8 ай бұрын

Some people defending self documenting code seem to miss the big picture. Comments are timesavers for other people going through your code because the comment describes what the code does briefly. Why spend time following the logic of code I don’t need to look at? That valuable time can be spent getting the work done. The arrogance associated with the self documenting code idea really starts to show in lost development time where other people individually invest time to align themselves with the code they’re reading. We’ve seen the pitfalls show up at various places in the development cycle when people fail to document code. Programming languages introduce all sorts to features to minimize code and not every developer learns all the features or chooses to use them. So when you encounter code like that, you have more wasted time figuring out the technique. There are several people we did not hire just based on their code future maintenance practices. It shows the scope of their thought processes reveals narcissistic patterns where they don’t consider how someone else now and in the future may be encumbered.

@theterabyte 7 ай бұрын

While a lot of people probably do mean "don't write any comments" when they say "self documenting code", I think for many that is a strawman. When I talk about self-documenting code, I mean the code has to say "what" and "how", so you should make it communicate that as clearly as possible. Code can rarely say "why" and the why changes much less frequently. Code says "what" and "how", comments say "why". Sometimes the why is obvious, and then self-documenting code doesn't need comments. When the why is non-obvious or helpful, add comments. When the "what" and "how" are non-obvious, make the code self-documenting, and if that is really hard, then use comments. It is always better to make the code say things rather than comments if possible, because the code will stay up to date when it changes, whereas comments can fall out of date. Also, regardless of language, all programmers working on the system understand code, so it is more universal. I would say the problem isn't self-documenting code, it is people who simplistically believe "Self documenting code means never writing a comment" and/or who write the same lazy code with no comments instead of changing the code to incorporate what the comment would have said. As AI code assistants become more popular, one of the things they are *exceedingly* good at is generating comments and explaining code. This job will become easier and less time consuming for people with the tools they now have available, but it is still as important as always in order to produce clear, maintainable code.

@forlooplogic 2 ай бұрын

I totally agree with your take. Yes adding comments does add more lines, but I’m old school and was taught to always use comments in my code. In my opinion comments allow you to document what you did and provide a starting ground for another developer who may have to maintain or make a significant change in the future. Using relevant method names and variables should be common practice, adding comments in my opinion is an act of love for yourself if you come back to it latter, or another dev who may come after you. Lastly, I love your guitar playing and how you use those clips as transitions for your videos. Robert | forlooplogic

@jwenting Жыл бұрын

Ideally code should be so instantly clear that it needs no comments. In reality that's hardly the case and comments help. BUT in my experience more often than not the code gets changed but the comments are left alone, having them become out of sync with the code. I tend to always add at least some Javadoc, and if methods get more complex more comments inside the method to explain what longer pieces do. And more often than not I get criticised for doing so by people claiming it's a waste of time and I'm being paid to write code, not documentation...

@SerenityDreaming Жыл бұрын

It seems like an entire industry of people who know how but not why. Lord help me what have I gotten into?

@vulpixelful Жыл бұрын

There are some codebases that require domain knowledge that can't just be evident by looking at code no matter how readable or expressive it is. Some of us devs would rather blindly follow the latest trending medium article on "best practices" than stop and think whether a principle applies to our team's situation.

@jonathancucuzza6358 Жыл бұрын

domain knowledge is at a higher scope than the code and should be documented outside of the code.

@vulpixelful Жыл бұрын

@@jonathancucuzza6358 💯

@jamesspinella7053 5 ай бұрын

I watched just long enough to make sure you weren't anti-comment. I've been writing code on the side for my entire career, almost a decade, and that alone has taught me that you must must must comment your code... Even if you're the only one who will ever see the code? ESPECIALLY if you are the only one who will ever see the code. I look at comments I left myself months and sometimes years prior and they have been a godsend. E: I just saw my other comment from a year ago haha

@zmdeadelius Жыл бұрын

I really appreciate how you're proposing a sane and balanced point of view in your videos. Especially when it's kinda common nowadays (or wasn't it always?) for people to blindly follow advise coming from someone of authority. I might have just 5 or 6 years as a small-time PHP programmer (solo), but still! Also, I hope people like you become a role model for everyone new to the game. Consulting on company websites and theme purchases from ThemeForest, I've seen too much arrogance and downright laziness coming from programmers. Some clean sound coming out of this guitar, well played! Loving the snippets of you playing in between chapters, really brings up the tone of the video. Looking forward to hearing more of these as well.

@damiandudycz Жыл бұрын

I really like how you interrupt your sentences with guitar playing. Makes the videos a lot more enjoyable for some reason. Thanks for all the valid content you create. I can refer to almost all you talk about, but usually I never even start to think about these things, so someone pointing these out, helps a lot to give it a thought. 9 years in programming (professinnally), so 1/3 of my life so far. Thanks and have a good day :)

@MikkoRantalainen Жыл бұрын

I guess that depends on your taste. For me, I watch these videos despite the guitar playing because the content is valuable but I usually skip forward when guitar playing starts.

@CarlAlex2 Жыл бұрын

To me the term "self documenting code" has always meant the source code of which the comments are a natural part - if its in the source file its part of the code just as much as the identifiers and whitespace added to make the code easier to read. Not adding comments when its proper is just plain stupid and/or sloppy lack of professionalism. Maintainability of code is important.

@chukukaogude5894 Жыл бұрын

I just found this channel recently and have been watching your videos to get an idea of how a software job is. Even though I have never had a software job, I agree with you wholeheartedly. I want to build my philosophy on this. Building the software is great but planning and executing the clean up afterwards is just as important. When I was in college, I built simple software projects and didn't care about it afterwards. When I came back to them after I graduated, I didn't understand anything I made. There was no comments. I used a, b, c for variables, all I cared about was did it work or not. Then I made a larger project, but I didn't plan it out well. When I went to go back to implement something, I realized even though I added some cleaner practices it was not modifiable without major changes. It's because I didn't think about the "clean up" and "maintenance" of it afterwards. I thought of software like a mechanical watch. Build it once and it's rarely tampered with the mass staying the same if its maintenance. Instead to me software was more like a walmart supercenter. Some things will stay the same, some things will be added in at certain times. Some things will be purged at certian times. Some things will be remodeled. Sometimes it will be shut down, someone else picks it up and turns it into their own thing. I am teaching myself, but I have to keep myself opened so that I don't create software that has bad practices in them and also software that others can actually understand and modify other than myself. Right now I am learning Java and I am reading about spring. (BOOK: Spring Start Here) I really need to see a real world group work together on enterprise software so I can understand how it all comes together.

@sealsharp Жыл бұрын

There's that saying "No battle plan survives contact with the enemy", which in my opinion perfectly fit's real software developement. Many teams claim to follow great pratices, but the reality is messy and getting things done and doing them in the way that is beneficial for the future means showing selfdiscipline in scenarios where the prerequisites you expect for things to work are not met. This can be be a shock to people, it's often overextending and dreadful, especially for young pleople who come from academic spaces and go in with the expectations that things will be like in theory. Your experiences with your own code are a first taste of the dynamic and everchanging nature or software and working with a team in a reallife scenario will add a few extra layers to that. It's good that you try to to improve yourself and your work and it's nice to see that it works for you. This is supposed to be both a warning and encouragement in some sense. Real team projects may become uglier than you'd expect, but you will prevail if you stay focused. And nice paintings btw.

@rdean150 Жыл бұрын

Whole heartedly agree. I've spent a fair bit of time over the past year creating reference repos to lure my team over from the self-documenting dark side, leveraging Sphinx and Jenkins to auto generate and publish rich API docs to GitHub pages, as well as coverage reports that automatically update a Coverage badge at the top of the README, so you have immediate access to up-to-date information about the state of the codebase and how to use it without needing to care about how it works under the hood. Libraries that can be trusted as black boxes preserve cognitive bandwidth. I also like DocFX for C# projects for this, but have found it more difficult to integrate into our CI pipeline due to its build dependencies. But like you said, even with the help of these tools, it is absolutely additional effort to write and maintain good documentation / comments. I think of it as an investment that increases the odds of wider adoption of libraries / APIs when creating tools I expect to be useful to multiple teams.

@theguy9067 Жыл бұрын

On the whole I'm with the self documenting code crowd. I don't think I've ever read usefully documented code or usefully documented public functions even. There are so many big public library methods that have documentation but you can tell whoever documented it was forced to against their will because of how badly described it was. There is the ideal and what I've experienced and based on what I've seen, I'd say, just write the unit tests, try write clean code and do code reviews and maybe here and there describe why something was done in a certain way. A lot of comments I see also don't even correctly describe what the code does for whatever reason. At the end of the day, the code has the final say on what the code does, not the comments. People will have to actually read the code in the end anyway to make sure of what something does, or they will have to test it anyway if it's public. Writing comments involves trust that the code does what the comments say it does, and I don't believe in trust. Often, if a method is complex and requires a comment description, the comments seem more difficult to understand than just reading the code. People think differently and the more complex something is the more varied ways you can explain it and this just adds complexity. Another aspect is it depends what industry you're in. In a lot of web dev stuff, you're doing input and output of data and many places follow the same patterns where you use the repository pattern and factory pattern and IOC and what have you. It's often sort of straight forward if everyone is on the same page with how things are done. Example you don't need to document a "Get" method as you can tell what it does based on the return type, the class it's contained in, it parameters etc. My first job all code was required to be documented and you'd have things like "GetThingyEnabledSetting()" with a comment above it "gets the thing setting, returns boolean". It's like oh no way

@AlanDarkworld Жыл бұрын

The whole argumentation of self-documenting code quickly falls apart when you realize that code, no matter how well-written and well-designed it is, cannot convey the "why". Why is this method call here? At the same time, the "why" is exactly what you should mostly focus on when writing comments.

@pablofernandogonzalezolmos8472 Жыл бұрын

I think if the class Tire has the method fill() or getPresure() is not mandatory to explain why are on this class, because it is explained yet on the business documentation where it is explained what is a car, what are it parts, and what is the expected behavior and limits of those parts. You want to know why is this class or this method there? Simple, because it was asked to be there by the business documentation, that precede the code-writing and design. Re-explain this on every class and method would be duplicate information that can give problems. Again, if the why is really needed because is not clear on the business documentation, please write all the comments you need. But, actually, the business documentation is usually poor or even not existant, there is no handbook, or requirements documentation and QA team have to figure out how to test the system. I can assure you, the QA Team will not dig on the code comments for that.

@anthonymoloney3671 Жыл бұрын

It's a bit old-school maybe but when I was taught to code I was taught not to touch the keyboard first, but to think through the design and basically write it out like psuedo code. Apart from letting me think through a solution before commiting to it, it eventually becomes the scaffolding for my code and the comments I will use. Early on I did neglect to comment my code and it would usually bite me in the ass when going back to my code and not really understanding what the hell I was doing. That really convinced me to not be lazy and adequately comment my code. Also, the person who taught me to code told me, imagine the next person who works on your code is like a Hells Angel! Best to make yours and someone elses life a little easier.

@sindle36 Жыл бұрын

I'd love to hear more from you. I'm not even in software development, you just have such great guidance and a calming demeanor. Wish you'd come back

@soberhippie Жыл бұрын

In my view, it's not a binary choice between self-documenting code and documenting. You can and should do both. And I'm fully behind the last point of treating one's own code as a _product_, which I think solves (or motivates and informs) the other issues raised here.

@lucidiusdonovan3807 Жыл бұрын

The theory of purely self documenting code is good and all but I have found that in practice in my decade in the industry is just not going to happen. Especially in more lean teams where fast results matter and business needs can change on a whim. There is barely enough time to refactor for performance, let alone prettiness. In addition, everyone writes code differently, especially with international teams, and it is a lot better to have a one liner comment before big blocks, complicated portions, etc, rather than having to read all the code contents or worse, having to breakpoint real data through to understand what it does. As mentioned in the video the function documentation, with parameter and return types comments is criminally underrated - and Vscode or intellisense does indeed reward this practice

@TakanashiYuuji Жыл бұрын

If I condense your argument it is this: If writing good quality code is not a priority, self-documentation doesn't work. I think that's a fair argument, but of course the point of self-documenting code is that you do end up with a quality code base. If you don't set out to do that, then you don't need it.

@peter-frankspierenburg9410 Жыл бұрын

Thanks! We don't always agree, but watching your videos helps crystallize my thinking when considering these kinds of issues. I think comments are primarily a hold-over from a time when people wrote code in assembler, or FORTRAN; in a time where a computer with 16K of RAM was considered decadent; where your variable names could be only two characters long. Now, to be clear, I'm not rabidly in the 'self-documenting-code is a requirement" camp; but I do prefer code that is self-documenting. I acknowledge that sometimes comments are valuable. However, my first reaction to "this algorithm is complicated" isn't "I should comment it" but rather "how can I origami the code to make it clearer". Strategies include refactoring the function into smaller pieces, renaming identifiers, coalescing parameters, and adding automated tests (on top of the ones I wrote TDD-style) that demonstrate how the function expects to be called, and how it reacts to failure. Maybe one day, my IDE will show me the automated tests around some api call the same way it currently shows me the comments? In my experience (call me lazy if you want) comments decay; particularly code-example comments. Sometimes it isn't obvious what comments need to change to correspond to some new refactor. Perhaps you've altered an API and there is a comment using that API in some other file. One of my fave quotes from Robert Martin: "They [tests] are written in a language that you intimately understand, they are absolutely unambiguous, they are so formal they execute, and they cannot get out of sync with the system." Anyway, thanks again.

@HealthyDev Жыл бұрын

Happy to help! I don’t agree with Bob here, but he’s a great value to our industry. The ease with which a practice (like unit tests) stays in sync with code is just one aspect to consider in choosing to comment or not.

@cfalguiere Жыл бұрын

Thanks for this post. This mantra dates back from a period of time where most of the code was a kind of script without structure, random names (e.g. P1 to P9 and v01 to v99 whatever the code does), and no additional documentation. When maintenance issues were obvious, commenting became mandatory and enforced by code reviews. It used to be great, but it caused code cluttered with non-sense comments just because it need some amount of comments. Comments have to be maintained as well, they was usually not, and commenting became useless. Methodology also enforced providing a design document aside. By the way comment lines counters where invented to insulate the number of "real line" because projects where project was sold "by the line number" instead of duration. This tool used to be leveraged to enforce a minimum percent of comments, while it is now used to enforce a low comment rule. Self documented code advocated to use clean code structures, known patterns and understandable naming to reduce the burden of commenting. At the same time class/function comments where normalized to minimize clutter. This was useful to change the developers mindset especially to fight the "comment every line of code" enforced by a lot of company's review books. The new rule was to move high level design and specifications to the design document and leverage naming and structure instead of comments for details. You need a strong message to change habits. It does not mean that comments were forbidden at all. A bit later executable specifications/unit tests provided better places to document WHAT the code does than comments and specifications. A "no comment" came back because it was assumed that most of the comments would explain what the code does. "No comment" should be a kind of what if to assess whether the code is written in a self documented way or if it is the best way to convey the business purpose. The metric is now used the other way around because high amount of code would suggest that those practices are poorly followed. It looks like this rule came back as a clean code practice with no context and some form of TikTok radicallity. Poor Uncle Bob :-) It reminds me the "no if" fuzz. I have assessed a lot of poorly written code, but I think the "no if" with every condition implemented as Strategy pattern was the worse. It is a pity because it was issued by a very clever person otherwise very good at programming. IMO people should study real books on clean programming instead of code "Jedis" with weird interpretation of those books.

@yazilliclick Жыл бұрын

I think a big reason for the 'self-documenting' approach is an over correction of the previous approach, and what was largely taught in schools: comment everything. Now we're in a place with probably too few comments, whereas before we were in a place with way too many comments. I can't count the amount of times I've seen comments to the effect of "// Loop through theList and do thing" before a loop. Or long winded comments describing simple private not-exposed methods. All that stuff makes for more reading, more clutter and more things that need to be maintained if kept. And since comments don't generate compile errors or bugs (directly) they often get missed and fall out of line with the code they're meant to be describing. I think there's a good happy medium for comments but personally I try to lean more to 'self-documenting' as a goal as I think that makes for easier to read and maintain code. However I also feel it's important to realize when that doesn't really work, or could be improved, with some commenting and that the commenting often is best to describe 'why' something is written like it is or has to exist.

@renegadeprime3871 Жыл бұрын

I think the problem is that developers have restrictive myopic methodologies on comments, it's either everything self-documenting or everything comments, there are challenges to both. If everything is self-documenting without traditional comments then there are areas where developers won't know the nuances regarding that section of the code like configuration, edge cases, remarks etc. If everything is a traditional comment then the developer will spend more time reading the comments instead of the actual code, developers run into the problem of creating comments that are not meaningful and cause clutter within the code base, take for example // this assigns an integer to this variable, this comment is quite useless and patronizing. My opinion is that the sweet spot is somewhere in the middle, where I want to read the code like I read a book, human readable and understandable, but with footnotes (comments) where they helpful and needed.

@TrackedHiker Жыл бұрын

Edge cases are a perfect example of making a comment that explains WHY. “Need to install npm packages inside Docker to avoid issues with architecture-specific binaries compiled or installed by some npm packages during installation.” (An abbreviated example of a comment I’ve actually written.) But please, please don’t tell me what the code does if you can reorganize, name, and structure your code to tell me without comments…

@MrAntice Жыл бұрын

I just want VScode to be able to not just check what goes into a function, but also what comes back from it. but tell me what it's for when i select it in the quick menu. Comments doesn't have to tell me the how of it. I'l read the code itself for that.

@Furball_ 4 ай бұрын

I always thought it was weird to not write comments when most editors allow them. The fact that I can read a fast summary that can be hidden if need be tells me what the method does seams so awesome to me personally.

@SufianBabri Жыл бұрын

Thank you for posting such a great content on this channel. I hope you're doing well and staying healthy. I guess different people comprehend the term "self-documenting code" differently. For me, I would avoid writing any comments if: - I am not writing a public API, which will of course need some sort of documentation. - My method/variable names are self-explanatory - I'm not doing anything weird (applying some weird algorithm, in which case I'd mention what I'm doing and a bit more links/info about the algorithm). I believe this topic deserves a few more videos, finding moderation between writing tonn of comments vs no comments Is the key here. I think having some real-World code snippets and discussing the issues with it will be a good plan.

@SufianBabri Жыл бұрын

@@dwnews_ hey you are not the real Jayme. Reporting...

@SamLeibowitz Жыл бұрын

I had a conversation with a colleague once in which he told me, "Every comment in a piece of software is an apology." I told him, "I don't know if you've read all of our code, but some of it could use an apology."

@xybersurfer Жыл бұрын

well said. much of our code could use an apology too haha

@matttamal8332 Жыл бұрын

This isn't black and white. A lot of it depends on context. There are places where documentation is necessary from a business perspective (reducing code complexity for maintenance), and there are also places where it's redundant and an overall cost to the business (the developer had to type it out, and it never gets read). Examples of a place where it's necessary is in a complex algorithm or function that does a lot of state manipulation or calculation. (You touched on this in the video somewhat) An example of a place where it's unnecessary is with things like Typescript React for Presentation Components; prop names & types, alongside class names fulfill just about all the documentation you need.

@SmokeytheBeer Жыл бұрын

Remembering to change the comments after refactoring is something I always need to remember. Nothing quite like sending yourself on a wild goose chase from reading an old comment that you forgot to change...

@NicoleTedesco Ай бұрын

For all the reasons you mentioned, I have no respect for anyone who gives me a lecture that begins with, “I believe in self-documenting code,” then proceeds to tell me how comments should not be created for whatever made up reasons they give me. Sure, I am a fan of writing understandable code, using descriptive variables and even being verbose with naming in an age where autocomplete is ubiquitous. The impulse to adhere to “only self documenting code,” in my opinion, is merely justification for irrational cost cutting (which does not cut costs) and laziness, frankly. Fine, whatever. If I am not the one calling the shots, then no comments. That is then not my mistake to make. I remember that the verbose nature of Smalltalk seemed to have an implicit hope that the code itself could be self-documenting. The idea of using English “sentences” as code in COBOL also seemed to reflect this dream. I can see a day when successors to large language models reliably generate usable code directly from human language specifications. That day is not today. Today, we still need programmers. Programmers will need to leave comments behind.

@Gumitto Жыл бұрын

I would say it depends on developer experience and level of empathy. Some of devs will never reach even skill of proper naming because you need to put yourself in others shoes to do it well (empathy). IMO at some point you can avoid comments, but first you should: 1. Know how to name things properly (BDD tests as docs!) 2. Know WHAT to explain in the comments 3. Design well -> KISS, YAGNI, design patterns, reduce complexity 4. Only then you can avoid writing comments, but you should never say "never write them"

@HealthyDev Жыл бұрын

I love this. Great observation about empathy for your team!

@TakanashiYuuji Жыл бұрын

I agree that making self documentation work, places a skill check on the programmer. But I think that's true for any kind of quality code base, regardless of the means. Similarly, a less experienced programmer can write comments, but are they going to be good comments?

@animanaut Жыл бұрын

"the customer does not pay for …" is the most stupid excuse. the customer might as well not paying for you, just the finished code. no tests. no continuous delivery… I write comments because I don’t want to be bothered with questions about my code on a Thursday evening :D also writing comments, as any other form of writing, helps me with "thinking". I have adjusted code many times after "thinking" about it a second time. but you have to strike a balance as comments sometimes age like milk

@HealthyDev Жыл бұрын

LOL yup. That's exactly what I was thinking when I first heard that response...

@Emperor9992001 Жыл бұрын

I subscribed to you 4 yrs ago and YT hasn't shown me one of your videos since. I'll try to catch more!

@smellslikeupdog80 Жыл бұрын

Hey dude, I just found your channel. I'm a recent bootcamp graduate, transitioning from a different career feild, and appreciate the perspective you have of the industry. What sort of advice would you give to anyone seeking work given the current economy? Do you have any previous videos of that nature? Thanks for any advice

@BulbasaurLeaves Жыл бұрын

Self documenting code definitely isn't a substitute for comments. However, I do think self-documenting code WITH well written comments can save a lot of time in terms of writing unnecessary documents outside of the code. A particular pet peeve of mine is when SDETs are required to write test cases with detailed steps for AUTOMATED tests. If no one is ever going to run the test manually and everyone on the team can look at the code and understand what the test does, spending half your time writing steps is a complete waste!

@mikewright2858 Жыл бұрын

Yes, good, clear code is NOT a substitute for comments, nor are comments a blank check to write crap. Professionals use both.

@SyssSeven 11 ай бұрын

Hey man, just checking in on ya. Hope everything is good.

@HealthyDev 11 ай бұрын

Thanks! I’m well. Hoping to return soon! Your support means a lot. 🙏

@music0in0my0head Жыл бұрын

I've always been a meticulous commenter because I know I have a terrible memory and need to relearn my code a lot. Then I joined a team and our very terrible scrum master/senior developer told me I had to stop because I had to write self-documenting code. He was let go 3 months later and I was so happy I hadn't stopped because it meant my projects could be picked up by anyone without me having to sit down and talk them through it. So now we're going to refactor his old project (because it is a cobbled together weird monolithic mess not ready for production), and my manager has started giving us 20% extra time for documentation because it saves so much time in the long run. With the fact that we work so many different projects through each other and people switching out, self-documenting code requires such a level of refactoring that is not necessary for the product, but is for understanding the product, that in our context it is not worth it.

@mattymattffs Жыл бұрын

It's too bad you stopped making videos. I just found this channel and find it quite valuable

@HealthyDev Жыл бұрын

Just took a break. I’ll be back 😊

@wizpig64 Жыл бұрын

when reviewing code that isn't explicitly commented, you can review the git blame to see the commit comments and issue links inside to gather more info about the intent behind the lines of code. in pycharm i believe you right click the line-number gutter and click "annotate", and then you can click through to the various commits. vscode must have this too.

@divinecomedian2 Жыл бұрын

Hopefully the commit messages don't suck. And hopefully the code doesn't predate the repo.

@WhiteThunder121 Жыл бұрын

Not documenting public functions of an API should be counted as a crime against humanity.

@Timelog88 Жыл бұрын

Range.Create(int min, int max) < no need for comments, it's really clear what the code does. Range.Create(int gte, int lte) < yeah, I added comments to this to explain what the arguments are. The second is an example of a range object we need to create from an elasticsearch response, and I did it because initially it didn't have comments and the other devs switched the LTE and GTE values. Lte stands for Less than or Equals and Gte for Greated than or Equals, which is terminology in Elasticsearch, but in our code we use the more readable min/max naming. So I am more in the camp of, if code really can not be written in such a way it is clear what the input and/or the output will be > write comments.

@jamesspinella7053 Жыл бұрын

Through my side projects I have learned when I need to comment and when the code is "documentation enough". I often work on a side project, leave it, and then come back months or even years later, and it's at that point that I know what I wish I left comments on. After a year or two, it really is similar to coming to a new project and reading someone else's code. I think we can just about all agree that comments should be used in moderation, and that "good code" doesn't have to be as-commented as "bad code".

@robertbrummayer4908 Жыл бұрын

Hi Jayme! Thank you for your video. I think Robert C. Martin has a good take on comments in his book "Clean Code". He sees comments more as a necessary evil than pure good. Personally, I like to express myself in code directly by using proper names and design principles, however I also add some comments that add value. In my career I have seen people so many times add redundant and noisy comments such as "sort items" before calling a function "sort" which adds no value whatsoever. I think there are bad and good types of comments to document code. I would like to see a video where you discuss concrete examples. In the book "Clean Code" uncle Bob already classifies types of comments which I find very helpful. Best greetings from Austria!

@silmelumenn Жыл бұрын

That would be a great video. Saying comments are good/bad is the same. Examples are needed to explain why a comment is good, what it brings to the table, or why it's bad. There is a difference between comments for intellisense, and comments inside functions. Those intellisense comments brings a lot of value if you are writing some kind od library, and not a DTO with getters and setters.

@Norstator Жыл бұрын

I was working for a company years ago that had introduced a monitoring system for cast iron parts for automotive industry. The lead developer was like "Our source code is self explanatory. If you like comments so much, you are by now supposed to insert them and I use them as an indicator on how good your comprehension level is". About a year after I quit I noticed they went bankrupt.

@LinxOnlineGames Жыл бұрын

I find comments that provide _context, and the why_ something was written the way it was, or discussing the paradigm a particular subset of classes expects is exceptionally advantageous, often with these types of comments they become a historical record that ultimately does not need to be rewritten as they provide nuggets of hidden detail. Note: comments that also point out gotcha areas are like gems in the rough.

@ArseneGray Жыл бұрын

I am not a full-time professional programmer, but a studied game designer and am working as an interface designer in automotive. So I have not all your studied programmers wisdom and knowledge. But when I do a personal project , like a small 2D game or something. I always comment my code in a way that it is describing what that code intents to do. Not what it actually does at the moment. In fact I found it extremely useful to think like this : If you cannot comment your code before you even type the code you are doing something wrong. Then I can use the comment as a help to understand what needs to go there in the code and what it is supposed to do. For me comments are a documentation of the specification of the program inside the programm not a description of the code in human language.

@eightsprites Жыл бұрын

Adding documentation to get/set/inc/dec methods has never increased my understanding of the code. Neither has documentstion about return type and most documentation about input arguments. Those are often required by the continues build system and vocal developers. On the other hand, documentation about intent (why) that isn’t stated in the code (how) is often useful. I do however think most comments inside a method is a sign of that a new method should be extracted and named accordingly and the comment should be removed. Documentation on API level is however very useful. Cause you never know the level of knowledge of the person using the API. Note: It could be YOU in three years from now! Document concepts. Document none obvious behavior. Document none standard error behaviors. And document it so someone outside your team can understand it. But please dont force me to document obvious or far away from the API code just to pass some automated test someone thought was a great idea too put inplace to delay the delivery of the product.

@etodemerzel2627 Жыл бұрын

Vocal developer. Lol

@HrHaakon Жыл бұрын

I think that parameters and output should mention nulls, if and when they happen and how they're dealt with and what they mean. Something like "editComment(String) : Sets the comment to the new String. String can never be null, will throw an exception." is plenty. I'm not asking for much, but I think that's fair. And yes, the method name was chosen poorly, and it was on purpose. It should be "setComment" or something.

@etodemerzel2627 Жыл бұрын

@@HrHaakon If you find yourself wanting "null comments" you're using a stupid language. Nullability should be represented by the type system. E.g. Rust's Option, Zig's optionals, etc.

@HrHaakon Жыл бұрын

@@etodemerzel2627 Right, I'm going to rewrite the entire codebase to Rust to handle nulls. That's not gonna happen. And even if you have something like Haskell's Maybe X, and what happens in the case of Just X is obvious, you should still tell me what happens when you get Nothing, because I need to know that. I could of course read the code, but I would rather hit ^q and get the docs directly. I just want to know what the rules are, and reading a sentence is faster than reading a function.

@etodemerzel2627 Жыл бұрын

@@HrHaakon > you should still tell me what happens when you get Nothing, because I need to know that. What do you mean by this?

@wpelfeta Жыл бұрын

At my work, our documentation usually falls into these cases: 1) We document all business rules (in a separate wiki complete with screenshots, not in the code itself). This is useful both for devs and QA and sometimes even the customers. 2) We document complex or lengthy sections of code that are not immediately obvious what it does at a glance. Though this is mostly at the programmer's preference/discretion. 3) We document any odd/abnormal business rules (within the code) to explain why the code is doing something weird. Usually a merge request reviewer will request a comment if they see something confusing. 4) We document our standards and architecture for anyone on the project to reference. Helpful for onboarding new devs. In general we prefer keeping functions as small as possible and names as clear as possible to self-document the majority of the code and reduce the risk of comments going out of date/needing to be maintained. But we definitely have a large amount of documentation. Though sometimes the best documentation is just asking a senior dev. lol. They are walking encyclopedias. And all that said, we still have a huge amount of legacy code that is undocumented. So sometimes you just have to dig through code.

@WarrenPostma Жыл бұрын

Business rules wikis always always rot, and diverge and can't handle the fact that the code exists in git, and it different branches over time. Depending on what you mean by business rules. If the business rules are more "domain specific principles that should never be violated" than "actually how the prodoct works", then perhaps your "external" models could avoid the death by bit rot that always plagues wikis. Wikis and knowledgebases seem like a great idea, and I have YET to see them not suck.

@williamshipley4841 Жыл бұрын

Many years ago I looked at the sort routine for a mainframe. There was several pages of assembler code with only one comment, which i still remember: "now I do something tricky". Comments are essential, but too many people simply comment the obvious, e.g. account_number++; // increment the account number The important things to comment is what is not in the code, but the context the code is being called in and what it is expected to do. Frequently I write this code prior to writing the comments.

@drno87 Жыл бұрын

I've worked on scientific and engineering simulation software where the teams were interdisciplinary and many parts of the code required specialized knowledge (e.g. of structural engineering or chemistry). Comments at least told you what parts were "safe" to touch and what the long formulas were trying to do. Otherwise you'd basically have to track down an expert to sit down and explain everything to you. We had one guy who was a disciple of self-documenting code. He left the company around the time I'd joined, and working on the stuff he wrote basically required a mini archaeology project to figure out what it purported to do.

@SeleDreams Жыл бұрын

I think the best is the middle ground, like, if we have a function where its behaviour is really self explenatory, there is no real reason to document much, but if you end up doing stuff where the behaviour might be confusing like let's say a function that is like this Object *MergeObjects(Object *a, Object *b) we'd definitely need a comment that specifies how it merges them and if it modifies the object a and returns it or if it instead creates a new object and returns it, as this is an important distinction

@poochy661 8 ай бұрын

I like your perspective on this, but for me self-documenting code is more about writing the code better rather than not commenting at all. As an example, one of my projects has some code to call the backend API to retrieve some JSON. All classes and functions down this chain are well-named and easy to understand, so no comments there. However, in the handling of the request, we have to check for a specific error, since we want to insert a specific error message only when that error is returned. It is not immediately obvious to someone from outside the team why this is checked and it is therefore documented with comments. The same goes for anything that may produce side-effects, units on variables, etc... I will agree with the point that I think I took it to heart so easily because of the prospect of barely writing comments after a schooling of commenting EVERYTHING. You have inspired me to go through our project and at least add comments to the major control flow, so someone new coming into the project has an easy time piecing the whole thing together!

@HealthyDev 8 ай бұрын

Nice take. That’s what I’m hoping for with this one. 😉

@kechidonick Жыл бұрын

i think you can use both, 12 years of coding and I see vars named v_id and a comment above a for loop that says "We go through the collection to get X" like I can see that but how is that useful. I´d love to read some good documentation on how to write good comments to improve my code, any recommendation?

@Tubingonline1 Жыл бұрын

His last words "Leave me some comments..." that says it all!

@sabriath Жыл бұрын

I'm old school, so my thought process works very different than the people coming out of college or on the indie scene. My methods/functions are usually very specific and if I have plans for them to be "public" (like a library functionality), then the only comments I will provide is the function call itself....no one should be looking inside a function that already works, unless it is for one of three specific reasons: 1. ensure no malicious code (functions should be small enough to be able to quickly identify these though) 2. update or deprecate parameter space on the call (though you would normally just overload the function as a duplicate until all systems have moved to the new function before deleting the old) 3. perform optimizations (compiler does quite a bit of that, so this shouldn't really be an issue for the most part) I usually write code without errors and fully optimized for both speed and space from the gate, but I'm a different type of programmer. I find comments to be distracting when looking at other people's work, because they seem to want to comment every single line, or every function even if only 1 other function calls it and is never left as a "public" utility.....it makes no sense, especially if the name of the function gives away what it does. I also prefer small variable names for function scope, but this is just a habit that falls in line with optimization. For example, I might use "i" for a for() loop, but after the loop, "i" is never used again....so in my mind, it's a "free variable" that I can use for other calculations if I need to. I try to use the least amount of frame space as I can in order to allow for more recursion depth if I need it. Most programmers nowadays don't keep these things in their mind because they've never had to deal with trying to write a game in 40k worth of space on a 1mhz computer in assembly, and it shows. So many people using the most bloated libraries as well without a care because "if it's slow, then the customer should upgrade their computer" mindset is sad. They sacrifice older customer comfort for lazier production. "I made a game with a billion mesh and requires a 16gb gfx card, stop being a noob and upgrade." It's disgusting...truly.

@andreasmischke Жыл бұрын

There's one thing that holds me back the most from writing comments: I experienced it a lot, that my own comments get "out of sync" with the code extremely fast. Meaning I write a piece if code, put comments (trying to describe the why or what) and a moment later I refactor and simply forget to check and if needed update the regarding comment. Does anyone know this and/or maybe have ideas how to improve that?

@R4ngeR4pidz Жыл бұрын

3:23 I'm not sure I agree, "it doesn't happen automatically" Maybe not while writing it, but when reading I generally add comments when I'm trying to figure out how a piece of code works. I'll often comment what it's doing as soon as I figure it out, mostly for myself

@KiddyCut Жыл бұрын

I like the idea, but im almost never 100% sure that my idea of what it does is actually correct.

@martinstanek3632 4 ай бұрын

A PR with a comment would not get approved under my watch. A PR with a "TODO" in it would get one into a trouble ...

@seriousjan5655 Жыл бұрын

One big reason you should write a coments: it helps recognise differences/errors between intention and actual code written.

@ejhott Жыл бұрын

I would love to see a video from you on how to figure out what the heck is going on when starting on a new team/project. I personally get overwhelmed and struggle with trying to put all the disparate pieces of information together in a meaningful way. I imagine that being a consultant would mean that you had to have that part down real good

@IgorKravets81 5 ай бұрын

I add comments to the top of the module to give an idea how it's used. And also definitely a line of comments on the quick workarounds. Just basically where I think the code itself might not be descriptive enough

@kfinkelstein Жыл бұрын

Where the heck would I put my TODOs without comments

@sylvainr0 9 ай бұрын

Thanks for the arguments. Will reuse it. Another way of looking at comments: it's a tl;dr for people who'll maintain your code (aka you most of the time).

@eric-seastrand Жыл бұрын

I would love a follow up video with some examples of the helpful comments you speak of. I tend to lean towards “self documenting code” because I feel like bad comments are worse than no comments at all, and I have mostly encountered unhelpful or downright misleading comments in my career. I only comment my code when there’s “magic” happening. To me, a comment explaining what a variable holds is a signal that the variable should just be named better. And a comment explaining what a function does means the function is poorly named and/or does too many things (and should be refactored). I keep an open mind though, and so still enjoyed your take on the topic. Commenting on error behavior seems fruitful but surely there’s a sweet spot on the level of detail. Help us understand where you draw that line.

@HealthyDev Жыл бұрын

I'll leave that up to each individual. It's too easy to come up with contrived examples and 1,000 ways to tear it apart for some contextual reason based on the viewer. Hopefully just getting people to think more deeply about this, and avoid adding NO comments due to the (name I hate) practice of "self-documenting code" at least offers some value!

@MiksCasal Жыл бұрын

Hey man, you're like my new online mentor. Thanks for all the wisdom sensei!

@KurtWoloch Жыл бұрын

I like to put in a variable called "current_action" which is assigned a string describing what's about to be done... which you would normally put in a comment if not clear. If an exception occurs, that string gets put out along with the error message so you can pinpoint the error location much closer. However, I do fill out the head comments in C# and VB (in C# they are preceded by ///), and I think you do have a point in describing WHY some things are done a certain way.

@cherubin7th Жыл бұрын

I at least like a comment to make a function clear, so that people don't have to read the inside and still understand. And inside a self documenting code that still has comments if needed, so basically best of both worlds.

@xybersurfer Жыл бұрын

a good time to add comments is especially when doing any kind of undocumented hacks, or making weird decisions for a good but non obvious reason. i've taken over as maintainer of a product and it dives deep into the internals of an underlying API, that we were not even supposed to touch. not having any comments explaining the choices turned out to be a disaster when some of the hacks stopped working. the fix was relatively simple in the end in a complicated piece of code, but it got delayed for months because i couldn't figure out what was going on (part of the problem being changing this generic code could fix it for one customer and break it for another). i've also noticed the same behavior in consultants, where they don't document their code. i suspect that the reason is that they think their code is not important and that it's all small one off changes. i think that's a terrible mindset

@grotoiler6104 Жыл бұрын

As a non coder having a short comment before a massive string of code is a massive time saver

@danielho5635 Жыл бұрын

I programmed in C in the mid 90's and made it a habit to use long, descriptive variable names and put in long comments when necessary. A new programmer came on board and I taught him for 6 months, and then I quit. During the training time, he constantly bitched and complained that my "habits" slowed him down. I finally talked to him 25 years later and he said that he had adopted my coding style and use it till this very day.