DON'T Comment Your Code 

My favourite comments to write: the link to the stack overflow article I stole it from

I added a comment here but then realized it wasn't necessary and removed it

My mantra is “just because it’s called code doesn’t mean it has to be cryptic”.

I’ve heard this for 50 years. In my experience, comments should (1) identify dependencies that are not apparent, (2) describe reasoning for architectural choices, (3) significantly reduce surprise.

"This code was hard to write, it should be hard to understand.", always goes down a storm at code reviews.

Most of my comments serve to warn against an urge someone might get to do X refactoring that seems natural, but that they wouldn't know in advance that it would break Y (performance) requirement, or in order to give more context to why something is done like it is, explaining a conscious decision that was taken in regards to a minor implementation detail. These cases are extremely rare, they don't fit into public interface documentation and are usually one liners.

The most beautiful code ever read a number of years ago had no comments either. It was a one page beautifully structured utility file, with fantastic naming and nicely sized composable methods. It wasn’t pretentious or trying hard to be “smart”. It was as if the developer had taken great care to speak through the code. I would argue that it crossed over into being a “work of art”. 🌟

The one type of comment that is always helpful: reference to external material. That might be the chapter of a standard that you are implementing, or the address of a project where you borrowed the code, or the chapter of a textbook that explains the vocabulary you are using.

I write doc comments for the intellisense, but also to write specifications, because it's unruly to leave it only to unit tests. Visually, it's also helpful to see the big blobs of green on the code overview next to the scroll bar in editors like VSCode.

Comments should tell why a piece of code was written and not what a piece of code does. This function was written to prevent the company from being fined by breaking such and such regulation. For example at one company they had a function for calculating overtime pay in the US. For most states at the time more than 40 hours a week counted as overtime; however, for one particular state over 8 hours in a day counted as overtime regardless of the total number of hours worked for the week. Without a comment explaining this, someone could modify the function thinking that the > 8 hours was a bug and getting the company in trouble with the regulators.

There are 2 types of comments I usually write. #1, API doxygen style comments about the functionality of a function (sometimes add pre, post conditions if not clear) #2, Explaining decisions: WHY I choose that particular solution. Otherwise I try to name variables/functions accordingly.

Mate, really wish you would drop the clickbait titles.

Comments remind me why/how I designed the code after I come back after a year. It saves me loads of time.

The comments I like the most are ones that tell me why and where something comes from. So if you are implementing a scientific algorithm writing down what paper you are implementing is REALLY important. Another common one is if you had to do external calculations for something. For example if you have done optimization and profiling to come up with some settings for a solver then it is really useful to write down why those solver settings are used and where the testing was done.

I do agree, that having single line comments in the style 'a + b // sum a and b' is useless, but you can only preach expressiveness with code for so long. There might be complex functionality, a bug, quirky behavior that is easy to overlook or a business decision that is way easier to understand with one line comment than having to read the implementation or that you turn a double take into a single take. Even a '// yes, this could be probably simpler, but it is an implementation detail and idgaf' is ok in my book... If it's stupid and it works, it ain't stupid. For libraries/utilities it is incredibly useful to add doc comments that describe behavior and show how to use the function (even inside the dev team - people come and go, hell, even if you are the only person writing the code), saving you the time that you would have to read the implementation and also help you avoid potential foot guns. Having comments on function parameters about what they do and how they interact with each other is also super useful, saving you the time that you would have to google/read the docs/query an LLM/read the implementation. Documenting code is also a better experience in some languages take the documentation seriously, compiling and executing code snippets to verify that the code in them is correct, so you can have tests in your documentation. Elixir does this and Go does something similar with their exmaples.

Some of the most beautiful code I've ever seen was uncommented assembler. It was an x86 linker I took over from the author. You could read it like a book, it was so well organized and named. I was the first other person see it and he asked me what I thought. So I quoted a little Keats: "Beauty is truth, truth beauty..."

I don't write comments in production code 90% of the time because I rarely find a situation where they help describe the code better than the code itself. I write loads of comments for code I share with students because I'm deluded into thinking they'll somehow read them even though they can't be bothered to glance at a textbook or even pretend to be awake during my lectures.

One of my criteria when marking my students' coding projects is 'how easy was it for me to get up to speed as a newbie dev on this project?'. Good comments can make a huge difference, not just for understanding the code, but for getting inside the mind of whoever was writing it.

I am thankful the jdk includes quite detailed comments that explains what classes are and how they are used, and what the methods are for. Too many third-party libraries are full of just empty javadocs, and visiting their API documentation is frustratingly useless. Interfaces need comments that explain why they exist and how they're used. Probably most public classes and their public methods need the same (if they aren't a method from an interface - the comment belongs on the interface in that case).

My company has a legacy project with really big js files with more than 1k lines, and really tightly coupled code. I feel happy when I see a few comments here and there otherwise, I would expend much time trying to understand.

issue when using abstraction and generic programming. sometimes comment can say what is NOT in the code and WHY. I've seen routine rewritten (in git history) 4 times to be eventually rolled back to the original with the comment like "this approach works, we tried using a common pattern 'x' but it doesn't work for these reason : xxxx

Literacy has some prerequisites. I had coworkers that didnt understand recursion and more advanced programming patterns. So far readable code is subjective. If you modularize code then you have various code pieces with different abstraction levels. What also often is missing is value ranges/ allowed values and return values. Sometimes you want a custom type but some time you want a more generic type (i.e. lists, arrays, sets, maps, strings, numbers, etc). I'm aware that I will not get it right every time. If I revisit old code then I check it and update/ delete as required, comments too.

100% agree. A particularly nice feature I like is "doc tests" in Rust, where each code snippet in doc-strings is ran as a test. I think it's really useful for documenting public APIs, as well as ensuring that the documentation examples are in sync with the actual code

It's a bit different when implementing things you find in computer science or cryptography papers. I could just leave all the calls to elliptic curve innards completely undocumented and just hope that whoever is using my library opens up the source code to figure out how an op in the virtual machibe functions, but that would be stupid. There are definitely cases for which good documentation is crucial, and the more complex or difficult the task, the more important that documentation becomes.

I wholeheartedly agree with this video. In most cases, when I feel obliged to write a comment, I know it's because my design isn't ideal, but I can't think of anything better right now. So I consider the need for that comment a code smell. One thing I did recently though after writing a small DSL over a really ugly third party library, was to write a lengthy comment for my entry point. It gives a quick overview and examples to get started with my stuff. I consider that a useful comment (Ofc the reader might find and read my tests as well)

This would be more helpful if you give realistic examples. I rarely if ever encounter comments that are as useless as your example with "adds two numbers". It's obvious to almost anybody that such comments are useless so what are we really learning? Would be more interesting to talk about edge cases where people might disagree. Personally I write comments whenever I feel like understanding the logic of the code without it would be hard or take too much time. Examples would be parts of the code that are related to a handful of other places in code out of hundreds of thousands of lines of code, that would take you half an hour of following references to understand. Or there might be some calculation that's derived from equations that would explain what it does, but it's simplified down for efficiency to such a degree that it's not obvious at all why it's done that way or why particular constants are used or whatever.

Comments are code that doesn't compile, can't be tested so its literally always a maintenance nightmare.

I reserve comments for when I have to make a hack to make something work or taken a shortcut that needs to be cleaned up later, as a hint to my future self or the next person to touch the code. The comment is there to explain why I made that "strange" choice and what the purpose is. In all other cases, in my opinion, the code should be "self documenting", it should be written with understandable names etc.

Where I can buy the t-shirt in video? it's literally me when I'm searching for something LOL

This reminds me a lot about Uncle Bob's Clean Code episode a while ago. Surprisingly these reminders are stil usefull.

For me there are 3 objectives 1. Why = Comment 2. What + Caveat = Document + function name 3. How = Each line of code

I normally only use comments to clarify what the code/function does (for complex templates, variadics or function overloading) or to provide examples of how it should be used (for complex functions that modify their behavior depending on how they are called). As an example, I once wrote a function that can be called either inside or outside a thread object and, depending on the method of calling, the code used to interact with it changes slightly. In all other cases I use automatic documentation generation. PS: @ContinuousDelivery Dave, you have a potential bug in your percentage calculation function. You are "/100" which is an integer division in most languages and you clearly want a double as stated in the return value. You should "/100.0"

It's difficult to apply this to database development, e.g. legacy oracle only allowed 30 character object names, plus you're often at the mercy of table and column names chosen by the domain, meaning that it's hard to write self documenting SQL or Pl/SQL, PL/pgSQL etc. unless you have complete control of the schema.

Many times I have felt that I was bad at comments and tried to "be better", it never stuck. Prolific comments were seldom very useful, and I think I would agree that situations where one is writing libraries or APIs is the main place where prolific documentation comments are actually super useful. I have come to think of comments more as bread crumbs. I would even say there is an inverse relationship between the logic in my code and the comments. Logic heavy portions are short, well named, and limited in scope so as to not need comments. Logic light portions, where a function may simply be a sequence of calls, I am more likely to use comments as a sort of index as to identify portions that I might want to skip to. Often I find that rather than proactively adding comments, I add them after returning to the code and getting frustrated looking for something, so I mark it off for next time.

The use of comments that annoys me is commenting out dead code. Sure if you're developing a major refactor do it, but don't check it in like that. Too many times I've seen developers reading this dead code and giving it too much consideration. We have version control to track old versions of the code. Use version control for storage of historical versions and comments for its communication purpose. Agree that code is the definitive documentation and that we should try to avoid comments by developing obvious software. One case I value comments is when there is a very specific set of config to make something work. We spent ages getting this config right for the database so please be careful changing this. There is a very specific bug this code solves. This code is in a very specific order and will break like this should you change it. Hopefully you don't get too many of these.

I somewhat recently left a TODO/FIX ME comment about removing a strange function after humanity kills the summer/wintertime conversion. Beyond that, I hardly ever comment code.

I code in assembler. I comment my complex bits of code so I remember what the heck I was doing when updating it months later. I don't do any fluff comments; usually inputs outputs and any tricky logic just after the function header. I also try to make the code by function and atomic to ease future maintenance or wholesale replacement.

Absolutely. Docstrings should be used, but only to generate end-user documentation for a library/module. And this should coincide with writing the code, while it's fresh in the developer's mind. There are two cases for commenting changes: 1) if the project cannot be trusted to preserve the history 2) if the scope of changes is artificially constrained (fix this little bug, little man, without touching our perfect design)

If I went into non-commented code I’d be seriously annoyed.

Of course comments often will hurt. 1) they waste time, 2) How do you know if the comment or the code is correct if there is a contradiction, 3) they require maintenance when the code is refactored (combination of 1 and 2)

"This adds nothing to our understanding of the code." Sorry, but this is objectively wrong. Comments do greatly help a person unfamiliar with the code to understand it. They help us teach new developers how we go about things. They tell us what the code is *supposed* to be doing, which is information you won't get, even if you stare at the code for a thousand years. They well us where specific parts of the processing happen. They tell us about the overall organization of the code. They tell us the path of processing. They tell us what events trigger the code to be called. In my own 12 years of software development, I have lost far and away more productivity from needing a comment I don't see than from seeing a comment I don't need.

You don't comment the what, you comment the WHY. pretty simple

I quite like the way go handles doc strings. They're more a human readable description and not just repeating the parameters. You're expected to infer how the parameters fit from their name and type. Part of the difference though is with public libraries the function cannot change what it does, only how it does it to avoid breaking changes. So library writers do not have to worry about the function changing with out updating the doc string. Instead they do have to worry about getting it correct first time as once published it cannot be changed.

I'm just glad I don't have to work with your bad habit of not fully commenting code.

I literally only write comments for the code review as we review each commit and it’s easier to annotate the code then to write up long commit messages that the reviewer will ignore anyway

Something I've looked for for years is a way of plugging diagrams into the code, viewable within an IDE - for certain problem domains at least. There are some algorithms where a single picture could literally save 1000 words. I've written a couple of plugins to do this, but it really needs doing at the IDE level to work well.

I write comments when I've selected a non standard solution due to external constraints. I also like to write headlines to make navigation easier when breaking code out into functions isn't optimal.

Writing comments that explain your code gives you the chance to catch and fix errors or poorly written or designed code. It's easier to fix a crock of s*** than it is to explain it away.

You should not be concerned with the implementation details when using an API. Hence a short textual description of API usage makes it much, much, easier for the consumer of the API. If you write _deep_ functions and classes a short description makes sense. Comments also have their place in implementation code as well, when you are working with more complex algorithms that are deviating from standard design or implementation patterns (or for example to describe strange hardware interactions in low-level code). API documentation should never mention implementation details, since that is information leakage by definition.

Starting out on an older Texas Instruments system (a programmable calculator running machine code) and a VIC20 with a Basic interpreter running on a gloriously expansive 3kb of RAM is where I learned to keep comments out of the code in confined to written notes. Coding in Visual Basic and HTML/CSS+SSI and XHTML/CSS+SSI with no environmental limitations is where I got spoiled and luxuriated by the opportunity to comment key lines of code. I still keep written notes. Some things just can't go in the code. So I knew from very early experience that there is a time and place to keep written notes and a time and place to to insert a comment or reference number/symbol in the code. Caution: This is a sole proprietor's approach to coding and may not work so well in a team where everyone "inherits" your work every day and no two people have the same internal dialogue language. And MAJOR props for the T-Shirt. That, by itself, would have been worth the👍 That T-Shirt made my whole day 😀

I am split. My mantra is: if you have nothing to say, say nothing. I.e. don't write docstrings that basically translate camelCase to "Camel case." Then again, I'd like to push the team to try to add helpful code comments and I I'd like to use linters. So I either write useless function and module docstrings or give up on clean linter reports; yes, I could also write "pylint:disable" comments. Just like compiler warnings, the only maintainable state is the clean state. So far I have opted to write the useless docstrings and push others to do so as well. Maybe one day I'll add missing-function-docstring and missing-module-docstring to the list of skipped Pylint checks.

There's a big difference between adding a comment for every obvious step in the code vs adding them sparingly to explain the intent of a complex piece of logic or as doc strings. The intellisense helper text alone is enough reason to always write doc strings for methods used outside of the current class. I fully subscribe to the idea that the function names and variable names should be chosen to be as obvious to their intent as possible, but it's silly to say "DON'T comment your code".

I've generally used comments to state my intent before writing the actual code. It helps me organize my thoughts while I'm doing it, and afterwards helps me understand what I was thinking when I was writing it. If there's a bug, isolating the part where the code doesn't do what the comment says it does can help hunt things down. Could this be achieved through better variable or method naming? Sometimes yes, sometimes no. Not saying don't make your code good and rely on the comments, but there's a difference between intent and implementation, and knowing where the intent differs from the actual results can be useful.

All code should be commented. I've never worked on uncommented that was easy to understand or work on. Comments must answer 3 questions: 1) what are you doing? 2) How are you doing it? 3) Why are you doing it this way? Echo comments are never acceptable. I've never seen any code that is self explanatory. Everyone has a different view of what is clear and that clarity changes over time.

- do you right comments in your code? - nope! - why, what are they there for? - to annoy, confuse and become obsolete The best comment I ever saw was "WTF IS GOING ON HERE??? I DON'T EVEN", on a method that was 200 lines long. it was added after the fact. did anybody write a test? nooo! did anyone refactor? nooo! The comment is probably still in the codebase After watching the video, a comment I sometimes find useful, is when I'm copying and pasting code snippets off the internet in a hurry, I include the URL where the snippet came from. In an ideal world, I refactor the snippet(s) so they make sense immediately, but sometimes you can't do that... time constraints and whatnot... I feel it helps to have the guide handy when I finally get around to cleaning up the mess I made...

//no comment

I'd write a comment, but it seems self-defeating.

I think that this video mostly falls under the category of "Click Bait" - an incendiary headline designed to pull outraged readers in. You actually had some vaguely useful comments but most of it was about examples of how bad most of the comments you see people putting in are useless. A much better video would have focused on constructive advice for how to comment code well in a manner which enhances its readability/maintainability/etc. ... perhaps with a headline more like "How to write the best code comments ..."

I always comment so I don't have to try to remember why I did something 5 years ago. Or if someone else looks at it, they'll have an explanation where else a variable is use or why a calculation is performed. It saves a lot of work later. Put in the time to give yourself technical surplus instead of wasting time later trying to decode your code.

I try too keep my comments to "here be dragons" stuff, either because it's totally not obvious but must be done like that for {insert} reasons or because it might make no sense at all BUT has a damn good reason to be like that. The later is mostly related to "this external call says it does x but DOES NOT, thus we MUST do yz to do x".

Enjoy blending 'both styles' into my writing. Clear code with good naming, and also prefacing each 'logic block' with a high level summary of what the following block or segment of code does. Such as,"Create if it doesn't exist;", then follow immediately with the code that checks and creates the folder if necessary.. More like a 'table of contents', so I can rapidly navigate lengthy scripts or libs. If both the comments and code are concise and clear, they act in a more 'symbiotic way'. I do draw a line though... I don't comment my import section, of course 😆 That's akin to 'teaching someone how to code'. Which isn't what comments are for... I've found I really appreciate this when I revisit code I wrote myself in the past. It always helps me dive back into code I haven't looked at in a long time, much faster.

That's paintful to hear. So much young and not so young developers writing bad code AND not commenting it just because they listen to advices like this one. I agree that there should not be a lot of comments, but after decade of software maintainance, I can tell you that I'm very often staring at classes having no clue what they are used for. Since good and very good programers (those that do know that maintenance is much more expensive than development) are no so common. Therefore, we should encourage developers to comment. To comment wisely.

I think the issue is that people think docstring is used to explain what the method does. The docstring is the equivalent of your method contract. This allows a caller to know what potential values are allowed without looking at your code. For example, in the "display percentage", the docstring would state which values of "percentage" are out of bound (e.g. percentage value from 0 to 100) if there is any specific restriction. It's not intended for the user that looks at the code and try to understand it, but for someone using your method to understand what it allows. It is not that important for internal use, but as soon as you start developing a library, they are mandatory if you don't want to write 200 pages of documentation on how to use your library.

In sql more commenting makes sense. Imagine working in a language where you can only do anonymous functions and use constants... There you go that's sql development. Here comments make more sense in both explaining what you are doing and why you are doing it.

I agree with everything stated in the video, but I want to add a little bit to the story. Working with closed libraries, legacy code and bad design software(Autodesk Maya) requires having workarounds and extra safeties that need to be implemented and there isn't really another way of doing it. Many times I would delete or redesign code that I've written months or years before, only to be hit with an error later, realizing why I've done the things I've done. Comments really help in that case to further explain things and prevent unnecessary work for a code that I alone use and maintain, and I imagine it would be essential for a group of people in that environment.

I write comments so that LLMs can learn what's going on ;).

Nice! How about documentation? Good old drilled and drilled documentation. How much should one write? I come from operations, where we only had discovery at our disposal, no documentation, we created it as we go. But how much of the documentation should a developer create? This works like that, A connects to B through gAmma in a way of theTA. At what level of abstraction, explanation detail, standard, templates (we had some just loving the word template, but it never worked)?

There's a C# analysis rule, I forget which one, that encourages writing things like, "if ((a && b) || c)", the interesting bit here being the extra parens for "readability". It's essentially using language operators as comments, and is in my view equivalent to the assembly comments example you gave. It's only useful if you don't understand even the most basic order of operations of the language. I know coders who voluntarily write this way as well, but I don't see the point any more than writing something like "a = (b * c) + d". To me, it hurts readability because now I have to slow down and try to figure out what it is they're trying to override. Worse, in a complex expression the number of nested parens can get pretty hard to count.

Personally, I use comments like section headings in a document. It helps readers get an overview of what is being done. Including me. I usually write these comments before I write the code. Very rarely, I use it when I have done something clever, though I try hard to avoid that. This means that comments are only needed when functions have several sections.

The idealistic view that code should be understood without comments only works in specific scenarios, including 1) all developers in the team are of high level, and 2) you don't share the code externally. There are many legitimate uses cases for comments that you're ignoring in your rush to rant against _bad_ comments. Library writers in particular need to document public functions and types with enough detail and corner cases to be useful for the consumers of the library without asking them to go and read the unit tests in the source code. Then you have comments that you write to explain architecural or design decision to your colleagues, knowing that if you don't, the question will come up in the code review anyway. Then you have similar situations but for code that might be too complex or abstract for junior developers in your team and you want to guide them appropriately. Also unintuitive exceptions that need to remain there because of some business case exception, as others have mentioned.

DocStrings makes sense for reusable modules/packages for others and I agree, they are only helpful for the public interface. Good naming and structure wins and should be the foundation and comments not a replacement for them. Another case I find comments useful: to explain performance tuned code. These are often not easy to understand in the first places and commenting these is valuable to make them more approachable.

Once, a client required that every single method was commented. We just ran a comment generator tool on the codebase and called it a day.

Just because you as the developer carefully chose your objects and methods names doesn’t mean that others will automatically be understand what your code does. While I agree that paraphrasing the code in the comments is just silly. Documenting your function header should be required. The reason is that I don’t always have access to the code and having a reference that documents the APIs is extremely useful

Writing code without comments is like saying I can write an article without footnotes, endnotes, abstract, and references because the reader should be smart enough to understand the text and context. I agree attempting redrafts to reduce comments, but at some point you have to move on

TLDR: Comment your code only when the code itself cannot be self-explanatory enough, e.g., when it would be ineffective to write a one-sentence function name. In some of those cases, commenting is crucial. So, let's make a video titled "Why You Should Comment Your Code," and then explain in a third video that "Well, It Depends."

Write nice tests. They are executable docs/comments ;)

For weak typed languages (JS) , DockBlocks help the IDE catch type errors.

I write comments to explain not obvious parts of the code or intentional empty if else branches (due to avoidance of using exclamation mark ! as negation in condition).

Writing complex math without comments is a suicide. In many cases the code doesn't look like math in analytical form. And math formulas without description could be hard to digest. DSP and financial apps are the examples. Yes, if a code just draws few forms in a browser and inserts the input into the database, that could be self-explanatory

Fully agree about the code being a human to human communication. IMO there’s two key points - the structure of the project should communicate what the project is about, functionally speaking - the code should communicate the algorithm/ the logic that is applied to respond to a given use case, as close possible as you could express it in plain english (the what) and express the how only in dedicated lower level methods . These lower level method could eventually worth a comment when the how is not obvious, like ie bitwise operations that are not immediately understandable. But as a general rule I tend to avoid comments, mainly because comments lies. Even if they are right at the beginning, that is absolutely not guaranteed, they will be quickly misaligned with the current implementation making everyone losing their time making assumptions based on wrong information. Actually, it’s like documentation. If it’s not at the center of the development process there’s chance never being relevant nor up to date . Side things never evolve synchronously, developers does’t have two phase commit actived . So the code can change but the side document not, nothing enforces it if not fully part of the development process.

Loved the tshirt.

Dave is destroying another fallacy, after saying no to pull request, e2e testing, agile..

I love the click bait title "DON'T Comment Your Code". Just wanted to hear what he has to say. I listened to the first few minutes of it, and that's all I have time for.

/* Don't trust the comments in the code also don't believe in everything on internet - Benjamin Franklin */

Trying to summarize the most important parts of good design in 15 minutes and mostly succeeding :-) I do not totally agree with the badness of function or class-comments tho. When trying to navigate a large legacy codebase I want to be able to glance att the context-popup from the IDE to get a little more info about a methodcall or parameter that is not obvious. In an unfamiliar codebase the abstractions selected is often not obvious and might change over time, thus a comment on why and what is often usefull. Also, in legacy code you can not expect that good design is kept all the time, thus again function and class comments become neccessary.

Comments that explain WHY rather than WHAT or HOW are sometimes very helpful.... Oh... then you said that anyway. :)

Ok, I agree with the _content_ of the video ... ... *but the TITLE was just click bait.* 🙄 I understand the business pressure to write clickbaitey titles, but with a bit of thought, you don't have to write a _dishonest_ title. Try this maybe: *"why YOU SHOULDN'T WRITE COMMENTS (and also when you should)"* _That's an attention-getter,_ while still being honest, so it doesn't stray into the realm of actual ckick bait. Thank you for coming to my TED Talk. 🤣

99% of all backups taken are also a useless waste of time.

JavaDocs are only needed in public (java) API:s. Comments are only used when devs are uncertain about the code they wrote is correct.

I may have missed it, but I would mention the rise as well of tools like co-pilot which include code explainability features.

Comments are often a proxy for comprehension. Developers who insist that other developers write comments typically aren't willing to spend the time actually reading and understanding the code as written.

This is a very biased opinion with inserts of straw man arguments. You can’t just say that people who writes docstring dgaf about making right design choices and writing modular codes. These are not mutually exclusive. There are times where you need to note down caveats and reasoning for certain design choices, which are at times based on non-local reason, quick-start instructions for a class, ideas to optimize code in the future when there’s more time, references to certain parameters in the function, the list goes on and on. Edit: Ah well, I couldn’t hold down my urge to comment after you shot at docstring for 11 minutes. You later addressed these, but I still blame you for a bit heavy handed towards docstring in the first 2/3 of the video 😅.

Not writing comments might be possible in a world with highly specialized programers. In today's world, that is just unrealistic. For example, if I write a C extension for a Python program , I cannot spend 2 years to learn all the nifty little detailed nuances to make my code correct, fast, short, concise and intuitively readable all at the same time. I want the code to solve my problem! So as a common courtesy to the poor ba*rt who inherits my work, I add a comment. Even in languages like Python, comments are often needed. Performance optimized numpy for example is unreadable by definition.

Nowadays there is a new type of audience that benefits from comments, which is AI tools. Yes they do also benefit greatly from code being clearer and well-named etc. But comments that add important reasoning and context surely makes AI-analysis more effective, as well. That said, what format or what type of information makes the most impact in aiding an AI to understand the code, is probably worth a study.

I'm 100% all for writing test codes as a documentation that contains working, executable examples. Also, I personally love to write lots of comments in both production codes and test codes. Indeed, I put a lot of thoughts and efforts to write comments to help the future code maintainers by providing the contexts, motivations and nuance behind the codes I wrote. Any kind of "best practices" cease to be good when they were mandated, which makes developers stop thinking anything other than following the rules.

!!COMMENTS ARE NOT VERSION CONTROL!! If you need to keep code around, control it with a flag. You have never needed to uncomment any code you previously committed as a comment. Even if you did, you probably broke production for longer than it needed to be because you had to recompile as opposed to flipping a flag that reverted to old behavior.

My comments are for my Swiss-cheese brain.

There's never a circumstance where 'no comments at all' is an acceptable strategy if your code must ever be maintained by someone else. Failing over to the version control system is useless for the vast majority of use cases. He's just massively out of touch with the vast majority of people who write & maintain code, & he's cherrypicking examples to find ridiculous cases. Do the rest of us a favor, & ignore this dude - comment your code.

Dave your book on deployment pipelines has been helping me immensely!! As always, thank you for your amazing content.

I support these comments.