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

[@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]

Better write the code with that attitude.

[@juliep1122]

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?

[@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. 👍🏻

[@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.

[@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.

[@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.

[@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.

[@_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.

[@nayaleezy]

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

[@homelessrobot]

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

[@nefthy]

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

[@viktorlernt6063]

Agree 💯

[@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

[@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.

[@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.

[@juliep1122]

Precisely this

[@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

[@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?

[@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.

[@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..

[@drawnfunny]

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.

[@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 : kzbin.info/www/bejne/jF64p4aBmp2djZYm15s

[@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"

[@Ольга-ж5к4й]

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.

[@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)

[@hamesparde9888]

I asked the person who was on my team why there were no comments in any of the Java code. I was having a lot of trouble understanding the code and I was specifically asking him about a particular function. He told me "the function name should tell you what it does." It was a 2,000 line long function with literally no comments at all.

[@BlackFlame208]

That sucks to read and understand. I feel your pain.

[@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".)

[@martinstanek3632]

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 ...

[@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.

[@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.

[@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.

[@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.

[@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.

[@silverfire222]

One big problem of comments is that they can contain bugs too. How do you test comments? How do you 100% ensure that the comments are right? How do you prevent anyone introducing bugs when refactoring the comments? How do you ensure that that comment refactoring has been done in all the places where it should?

[@HealthyDev]

You can’t prevent those things 100% with code either. No matter what refactoring and code coverage tools you use. It comes down to one thing - diligence. Being thorough, completing your work before moving on, and getting a second set of eyes on things. Even with that, no comment, algorithm, or piece of code is infallible from having problems introduced at any time.

[@silverfire222]

​@@HealthyDev But at least you have something to rely on. If someone breaks the code, but you have a good suit of tests, you may notice it. If a comment is broken, then the only way to notice it is if someone discovers it. Though, I would like to clarify that I think that comments have their usages. It is just that many developers out there missuse them. I recommend the video in the Code Aesthetic channel about this topic, where I think it is very well explained (not spam intended).

[@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.

[@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.

[@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.

[@theterabyte]

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.

[@Replayer-Realm]

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.

[@Tubingonline1]

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

[@phildem414]

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

[@philipoakley5498]

+1; Code is an *implementation*, not a *purpose*, nor a *rationale* for the choices made during the production of the product. Documentation is the totality of these differing reader needs (and more). Code which is easier to read is better code, but we mustn't let our inability to write in native grammar be an excuse for not documenting the work. It's not easy, but try.

[@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?

[@QuakePhil]

Self documenting code should be the goal, but a rule prohibiting comments is just wrong

[@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. :/

[@krfloll]

Where the heck would I put my TODOs without comments

[@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.

[@jimmyhirr5773]

I'm not convinced by what you've said because the people you've quoted don't represent me. It's sad to see how the advice to avoid comments has been misinterpreted. If you go to the source and read "Refactoring" and "Clean Code," you'll see that they don't say "never use comments." What they say is that comments are usually a suboptimal way to express intent. If you have some code and a comment that explains what the code does, then the code repeats itself (DRY violation). It also creates a maintenance burden because there are two things that need to change whenever there is a functionality change. The comment can become outdated if someone forgets to change it, and there's no way to detect that it is out of date. Much better to have class, type, function, variable, etc. names and designs that are descriptive, and unit tests that show intended behavior, instead of masking smelly code with the perfume of comments.

[@HealthyDev]

That's cool, I'm not trying to say everyone is doing self-documented coding practices because of the things I've mentioned. I know some people are applying it properly. I posted a follow up on the community tab with answers to frequent comments that may be worth checking out: kzbin.infoUgkxmnirMfc9YcSrH1vVVcB_2oNBfkhY1_oQ

[@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.

[@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.

[@KrisVuk]

I'm a PE at Amazon with quite a bit of experience. Just mirroring my own opinion here but comments should really describe the why when the why isn't immediately apparent. If the how isn't immediately apparent, that's almost always due to unclear code that requires a refactor. Splitting up large methods, good naming, etc. If you find yourself wanting to document the 'how', take a step back to better structure your solution. Now there are some cases where the 'how' really is complicated. Some code like the handling of matrices in ML/data work and other mathematical formulations sometimes benefit from a higher level comment. Also don't be shy to go with some longer names when needed. This advice hinges on you writing fresh code - it gets more complicated when working in legacy code as entropy rises. That sometimes requires significant refactoring and let's be honest with ourselves - we don't always 'find the time'.

[@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.

[@LDdrums20]

That's a beautiful gretch guitar man

[@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

[@seriousjan5655]

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

[@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?

[@theugobosschannel8466]

Nowadays, developers will waste lines writing about this GNU Licenses or that MIT License. When they could’ve used those same lines to explain to us what the class/code is supposed to be doing.

[@sealsharp]

I laughed.

[@forceghostpepper]

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.

[@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

[@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 💯

[@andrewmusholt9327]

You don't think comments are necessary until you work on code you haven't touched in years :D

[@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.

[@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.

[@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.

[@jimmyhirr5773]

Disappointed that you didn't answer the question in the title. My understanding is that code comments were invented shortly after the first assemblers. In assembly language, the names a programmer can add are limited. There are labels, constants, file names, and macros. And that's about it! There are no function signatures, no variable names, and no user-defined types. Any subroutine can access all memory and registers and can jump anywhere. In a situation like this, comments are essential to understand how the code works. Reading assembly language code without comments is about as difficult as reading the output of a disassembler. Modern, high level languages are much less prone to this problem. There are many more ways for programmers to express themselves in a high level language than in assembly. And the intent of the code is clearer when the language supports structured programming and the compiler or interpreter handles memory management. This means fewer comments are necessary to explain the same amount of functionality.

[@HealthyDev]

I posted a follow up on the community tab with answers to frequent comments that may be worth checking out: kzbin.infoUgkxmnirMfc9YcSrH1vVVcB_2oNBfkhY1_oQ

[@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.

[@jordanhenshaw]

My current process: 1. Write it to get it working, add normal inline comments, don't overthink it, just get it running. 2. Later, when I have time, refactor the entire thing to be self-documenting, remove all the inline comments, and add a paragraph-length docstring at the top of the method that explains WHY in plain english in long form. If it's a really complicated method/class with a lot of requirements and context, I'll add a list of steps it takes with explanations beside them. This way, you can build a thorough mental model of what the code will do before you read the code. When you understand it from plain english, you then read the self-documenting code itself. It's self-documenting usually because all primary tasks are separated into individual methods and those method names tell you exactly what the small method does. If it's a super complicated, mission critical, long chunk of code responsible for all kinds of diverse operations, I'll have basically an essay at the top of the file that explains all of the context of what we're trying to achieve. Then I'll write out all the steps that are taken to solve those problems with documentation codes beside them. Then, in the code itself, I'll add each segment's documentation code inline. That way, you have super detailed inline comments without adding hardly any clutter. Can be a bit of a pain to have to scroll up and down a bunch of times, but you're really supposed to read the essay at the top and then read the code. But this structure is only for special cases with a ton of complexity and mission-critical details.

[@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.

[@dandymcgee]

Comments are woefully underrated, and well-commented software and libraries are an absolute godsend. I am the #1 commenter on every project I've ever worked on, because code IS NOT self-documenting in any way other than it says literally what the computer should do. The code does not self-document WHY the programmer wanted the computer to do the thing the code is telling the computer to do. If that's non-obvious for any reason, leave a comment! Pleaseeee. Everyone will thank you, including yourself later on.

[@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.

[@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.

[@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...

[@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?

[@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.

[@jamesspinella7053]

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

[@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?

[@skaruts]

The problems with self-documenting code are that, on one hand, whether your code is actually self-documenting depends on who's reading it, as people think differently and some might still not understand your code. And on the other hand it can also be too self documenting, to the point you're diving into a rabbit hole of a billion tiny functions that you have to keep jumping to over and over, and it gets harder to follow and reason about than if you could find more code in the same place. Another problem with self-documenting code is that it's often very much wishful thinking. It's time consuming and it requires a lot more work. You can feasibly do it at times, but lets face it, a lot of code is ugly because it has to be, because the algorithms are complex and you either focus your time and brainpower on making it work or on making it pretty, because making it pretty is in itself a complex puzzle that would take you many hours, and it's asking for introducing more bugs.

[@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.

[@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.

[@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.

[@forlooplogic]

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

[@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

[@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.

[@SyssSeven]

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

[@HealthyDev]

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

[@thydevdom]

I’ve become better at “self-documenting” but without comments I STILL find myself having to read the code for many methods/functions to clarify what it does.

[@Kiev-in-3-days]

Lack of clear context? Not modular enough? Too big functions? Self-documenting code is doable. Keep trying! Refactoring is the key.

[@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.

[@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.

[@smort123]

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

[@Furball_]

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.

[@davidmcclellan4621]

Hope all is well with you. I noticed you weren't showing up in my sub box so I came to check on your channel.

[@robertjones6891]

I've never once seen proclaimed "self-documenting" code that didn't require an extensive Confluence page in lieu of in-line comments. Individual blocks in isolation maybe, but how is it being used elsewhere? What's calling it? Why?

[@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.

[@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!👏👍👍

[@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?

[@scottlydon4631]

How are you mic'd?

[@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

[@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.

[@redcrafterlppa303]

I'm currently on 2:23 for context. You seem to mix up comments and doc-comments. Which as far as I understood the no comments practice is different. Doc comments for library code used in a documentation generator are not discouraged. The idea of self documenting code is to make application code more readable. You don't want a do-comment on every function in application code. It makes files long and difficult to traverse. And sticking a comment on an string to int function : //converts string to int Can be expressed in the function signature without a comment: int convert(String source); Also writing a comment on every line of code describing what the line does is obviously unnecessary. Summary: In general write a small comment if something is unclear for example : int index = Math.sqrt(a*b/c); //calutes the Newton index (made up for example) If you write a library use doc comments to document the public api functions. If you write an actual application use meaningful function and parameter names and comment only difficult parts s.o. Edit: I watched to the end and actually agree with many of your points. But as I speculated they all fall into the category library doc comments. For my understanding of self documenting code it isn't about not write doc comments. It is about not cluttering an applications source files with useless comments. Like: int x = 5 // initializing the variable x to five. If the purpose of a function isn't clear by its parameters and return values it should be refactored. And as I already said above commenting an algorithm that is difficult to read is totally not not wanted.

[@lua-nya]

My favourite way to document code is with tests.

[@lua-nya]

This is not to say all ways to do comments are bad documentation, or all ways to do tests are good documentation.

[@scottgreen3703]

I used to comment almost every fun that made my workvery easy to grasp for the next programmer but the company didn't value my work they though that our new programmer is faster and able to understand the system quickly and the new programmer didn't mention to them it was easy for him because of my extra time i spent detailing things , so from last year i made my decision to not write any comments the best ill do is self documentation

[@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.

[@GrumpSkull]

How can you possibly have self documenting code when working at a very abstract low level?

[@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.

[@dragonfalcon8474]

Hey Jayme, noticed you haven't had any videos in a long time. How's it going?

[@HealthyDev]

Hey, it’s going pretty well. Had a bunch of personal stuff to deal with outside the family and a big project. Hoping to upload again soon though!

[@dragonfalcon8474]

@@HealthyDev No worries man. Just glad to hear you're still going strong it sounds like! I'm a software dev that is transitioning to Product Owner at a large defense company. Been an interesting ride so far. You videos help me identify problems within our organization and help fix them!

[@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.