Don't Write Comments | Prime Reacts 

I go a step further than not writing comments, I run it through an obfuscator before committing to the repository ♥

No wonder Tom didn't add comment support to JDSL. It's self explanatory. Tom is a genius.

I blame Scott for not explaining that comments weren't implemented in JDSL.

The best comment I have ever seen in a code were: ! fiddle with variables and print stuff It was in a very old Fortran code for doing configuration interaction calculations for atomic nuclei.

Here to the clean code camp who say the code should document itself: This is what your function names end up look like: - setupPageSizeA - navigateToSectionFourteenParagraphThirtyTo - handleTopLeftCornerButtonClickWhenUserIsUpsetAndFrustrated ... The names are so meaningful that you don't need to write comment at all. And Shakespeare shall be proud of ya.

Linus torvalds said it well: Dont describe your code, describe why you are doing something (if it's not obvious). It's because otherwise the comment does the same thing as the code, so your code should be readable so you dont need comments. But sometimes you need to write code in a specific way for uncontrollable reasons (external issues such as driver issues, some external service behaving in a weird way, some library requiring something that is not obvious, etc).

With the qualifier "most of the time", I absolutely agree. Just yesterday I was cursing my heart out, because code was changed to do the complete opposite of what the comments said. Nobody maintains them, half the time people don't even read them and it takes on average 2 weeks before "redundantly repeating what the code is telling me already" turns into "blatantly lying to my face".

Is this video made by Tom the Genius?

Real talk: I usually only put comments in code (be it JS, R, Python or SQL) when i am referencing a business rule that needs to be understood. Preferably simply listing the business document link so if code needs to be updated they can go in-depth as to 'why' something is the way it is. I've found this is a big help in research settings where government & sponsor rules and regulations shift ever so slightly quite often.

All these guys have a good idea, and then try to apply it to all situations everywhere. Sometimes you need a comment, so write a damn comment.

Rust is the first language where I felt like comments were right. The language is descriptive enough that I dont often need to write comments explaining what's happening. The built in testing system means I don't need to write comments explaining edge cases or intended use. Docstrings with tested examples are probably the best documentation I've ever seen in normal library code. Obviously other languages can avoid comments too, but in the looser or harder langauges I need comments more.

I think using comments as headers to segment areas of a large code blocks, is something useful. It allows quickly skimming through code, without having to read the whole thing.

If you can make your code readable enough and good enough, don't write comments. If you can't, Id rather have a commented steaming pile of garbage than a steaming pile of garbage with no comments at all.

50 year veteran here. If you have ever come across code you wrote 30 years before and thought "WTF was I doing this for?" because you know you had a really good reason but you can't remember what it was, then you know why comments are crucial. As a team lead I would refuse to OK code that doesn't tell me what a piece of code is supposed to do without having to read the code. It should also tell me the reasoning if anything is "non obvious".

As an embedded engineer, even if your comment is "this code is f'd-up" and at that point, even if it's a lie --- it's still a warning that it is not going to work like what you will work like what is epxected. That's huge. That's helpful. I worked with this stuff that was only very loosely embedded-to-JS, and copying it immediately via clone seemed silly --- but the comment saying, "this is f'd-up, I get it"... GOOD STUFF.

Me writing comments for my future self has saved me, sometimes just the why, sometimes some what's to make a piece less dense (sometimes I write dense code when I'm in a flow, but I won't be in that same mindset a year later). The best thing to do is to write comments to someone out of the loop just to bring them to speed. Put it where it matters, so if that specific thing changes, so does the adjacent note/comment. Those that don't give themselves/others future notes have not ran into that issue. After they have the experience of going into different projects and having to revisit the past and realize they can't put together what they thought was obvious, they have to read a bunch of code to catch up to that mindset for that moment, then they'll have wised up to what to put, where to put it, and smart enough to keep those important bits up to date.

I love how "Tom" the megamind genius is a recurring character in these stream highlights

I honestly don't care that comments can lie I'll take 75% accurate with some context over no comments any day The real issue is that comments need to be reviewed with the same scrutiny as the code they're describing

That only applies to those who are just calling APIs and barely have any advanced logic in their code. When you have advanced mathematics and complex algorithms and equations that are based on geometry, you'll need to explain what are you doing and why and why didn't you go for the other obvious more intuitive way. That's what comments are for. It's not to explain what's happening, it's to tell you why it's happening and what was the developer thinking.

Very nice, agree in most points. Now, try to write an assembly code with no comments and come back 6 months later

Comments are useful for writing down my thought process in the context of a piece of code. I find that it's better to just get things done as fast as possible, leave some comments describing and explaining the function and purpose of the code, then return at a later date with a fresh mind and refactor everything. It's kind of like writing an essay. Your first draft will usually be ugly, but it has all of the ideas that you want to deliver. It's only when you return to it later that you are able to edit it with better phrases, more appropriate words, a cleaner and more clear structure, add, or even restructure some of the ideas.

This guy’s voice is awesome. Like, I never thought I’d be able to tolerate a voice like this but he’s even more hilarious because of it. I can’t get enough of his videos.

The math in his if statement example had me laughing 😂. And he did it so smoothly, that it doesn’t come off as inappropriate.

Just watching this channel the last year made me a better programmer. Love you Prime, thank you

I'm a beginner, this kind of videos frustrated me a lot because of the titles "don't write comments", "don't do this", "dont do that"... And, a beginner life is like: -> Starts to learn about comments -> Start learning how to comment well -> Start commenting well =-=-= 1 Week Later =-=-= *RU-vid video telling you to not write comments* Beginner Conclusion: All you've learned is wrong. =-=-= Sometime Later =-=-= -> Starts to learn about OOP -> Got used to OOP -> Start writing good OOP code =-=-= 1 Week Later =-=-= *RU-vid video: "OOP IS WRONG", "OOP IS THE ROOT OF ALL EVIL"* Beginner Conclusion: All you've learned is wrong. And this applies for all of the things I've done. ALWAYS, sometime later, a video will show trying to discourage me or prove that what I'm learning is wrong and it shoudn't exist. I bet if I start learning Rust, 1 week later, a video will show to me telling that Rust is "bad". But I don't fall for this anymore. I learn by myself now.

HTML is not fully structural, you do not need to close since they aren't allowed to be nested, the language will auto-close

Programmers that can't be bothered to update a comment to reflect their change don't deserve to meddling in the code to begin with.

Comment now perfect later. Comments are context. Beginners need context and have to learn to communicate it. Technical writers need context to document. Senior devs create context and have to clarify it. Managers and stakeholders need explanations from everyone else depending on that context. The idea of not commenting is arguing for a perfect ideal code that will never exists. Just comment.

the comments should be about the design rational, the trade offs, business requirements and context. If you're writing a library that calls some other service, the comments should be about the quirks of the service and any odd stuff that you found. The comment should be about "how do I help someone maintain the code."

Nothing to add here, just let me state a fact... Tom is a Genius.

I am a fan of triple-slash comments in C#, my thought is that if you need a comment inline, it probably should be it’s own function and then inside the triple-slash I can detail what is being done, what are the concerns for the comments, and why did I decide to do this. It also allows me to explain concepts. It also can be used by auto-documentation tools to make documentation. And then there is a team effort to update and scrutinize the comments when we change things up such that people can better understand. Self-commenting code has been a nightmare to work with in the past, because evaluating decisions for refactors suck.

Watching ThePrimeagen instead of sitting down and coding is the real copium

I've been struggling with a relatively short function as of late regarding datetime conversion and various adjustments with a dynamic axis. The code is commented a lot and it has taken me over a week to understand it. Functions and classes are intertwined, most variables are kept short for whatever reason, lists and dicts are unpacked into objects, functions are passed in init, of course no type hints (yes, it's python). A simple thing like using longer, easier to follow variable names would solve so much and dynamic typing is the absolute worst thing about python.

Maybe it’s just because I mainly do embedded programming, microcontrollers, FPGAs and similar, but comments are very useful sometimes and I would rather commented code than non commented code, if the comments don’t make sense you can always fall back to just reading the code.

At my job we often end up going over the code in a pair of reviewer and author. If at any point we need to stop at a piece of code to explain why it's the way it is or we stop because even the author needs to think about it it's always a three step process 1) what does the code do exactly? 2) Can it be simplified or cleaned up? 3) If no, put a commend explaining why the code is the way it is It's a rare occourence, oftentimes to adapt some weirdness from a third party library or incomming data. But when it happens the comments do actually help. Basically: If you read a line of code and your first thought is "WTF is this?". It's probably time for a comment

I like putting a "project philosophy" file into the documantation which gives a general idea of how the projects structure is intended to be. Explaining which services there are, how the code can be extended, etc.

My first computer science teacher made us write out what our functions were going to do before we could code. We also had to put in the comments which function was calling which. It is actually easier to run my code through an anti comment program (just deletes any thing in a ‘’’ or after #) than to break this habit unfortunately.

I'd say the big exception to this if when you write code to integrate with an external system like a ERP system or something. Having a few comments instead of being forced to spelunk ERP documentation to understand why some seemingly pointless details are included / required saves so much time.

I find comments that explain the code useful in two circumstances: 1. As a block comment at the top of a file, summarizing what the file does 2. Comments breaking up sections of a large procedural function that does several complicated steps. Many people will say "if you have several complicated steps, you should just split them into multiple named functions". But I disagree with this. When you split them into functions, you're implicitly saying "these functions can be called Independently, and perhaps in any order". But in the case of the large procedural function, each step must happen in a very specific order, and the steps shouldn't be invoked in isolation. Having them in order within a single encapsulated function is much better for expressing how it should be actually used, and comments can just help summarize what each complicated step is doing, and provides a little break between reading each section.

One point: in embedded programming, sometimes comments are almost necessary. Writing some random number to some random register or similar can be very confusing otherwise. For example: Accessing the DRW register over SWD after setting a new address in the TAR register requires one dummy read first. So, you set the register you want to read from, and then you read twice. Without a comment in there, that seems like a bug. A simple //dummy read after the first read explains what happens.

I worked for a company once were we had a new junior hire that quit the first day, citing the lack of comments as the number one reason

As always, your videos are incredible! 00:06:52 I think optionals came from the type theory (I think it's related to monads like those in haskell)

Software Engineer speaking: I will ensure anyone who doesn't use/maintain clear and concise code comments will be assigned as far away from a keyboard as possible.

you feel forced to comment old/legacy code to hopefully guide the next sucker to greener pastures, also python is epic

3:40 in this scenario, I would argue that you should not name the variable "FIVE_MINUTES" because the variable name can become misleading just as the comment did. If you change 5 to a 3, you might forget to adjust the variable name.

Is not similar to in that it cannot be nested anyway?

I agree! I don't write comments that explain code. I write comments if my code is weird or violate a basic principle, like a query inside a loop, that explains why in that particular situation I had no other choice.

I don't think that's even controversial. I've never met any professional who writes a significant amount of comments. They're just unnecessary most of the time.

What theme was that when you showed the editor to do quick math example?

Option/Maybe/Either: pretty sure it was Haskell again. It's wild how many programming concepts originated in that language.

Thats why Tom said f u to comments in his JDSL , Tom is a genius

Comments never lie, they just don't tell the truth!

I work in hardware emulation... the domain essentially requires huge amounts of state and logic in the code to do its job (emulate hardware, which is inherently extremely stateful and extremely combinatorial). We try to manage this as best we can, but you still need that core logic *somewhere*, no amount of abstraction or naming functions will help you here. There's so much external knowledge to the code to make sense of variables and equations that comments are basically necessary to say why XYZ is done at point ABC.

I was repurposing an old computer the other week. It is over 10 years old and has code from some of the projects I was doing while learning front-end dev. The comments I wrote in there killed me to read. Practically every block of code had a header like "// ---- Functions ----" or dumb stuff like that XD

I usually do some kind of chapterization. Say I have a controller function which is long. I specifiy where I validate and parse the inputs, where I do bussiness logic related stuff, where I write the data into database and where I send a successfull response. I also do the day with types. Each type has a file, the file contains, type definition, type builder section, trait implementations, error type and... It helped my navigation a lot.

I've seen Primagen confuse borrow checker with allocation & deallocation twice now. Though this time he's somewhat closer to the truth than the last time; because unique_ptrs *does* involve life time management. You can still share a unique_ptr via reference arbitrarily.

Golang got a test suite which validates examples via code and expected output in a comment. These comments are later published in API docs along with the build

Man what a worth while watch was Tom's Jdsl video. Probably they were the same stream but as someone who just watched clips is funny AF getting a reference to it

I use comments for 2 things: 1. work in progress, so when I come back to it I have an idea of my line of thought and can finish the work 2. To describe an entire script/set of functions, this is so someone doesn't have to read through the file to know the details of what it is accomplishing. This isn't always necessary but I think it is a good habit and really helps people still being on-boarded.

In my personal programming language, Symta, all typenames start with a lower-case letter, while all data variables with an upper-case letter. Yeah, I'm a Prolog fan.

I love when a dev explains what the code is (supposed to be) doing, makes it easier to audit the mistakes if the logic doesn't line up. Someone else being able to tell what your code is actually doing, and it doing what you think it does are two different things.

Comments need to exist to justify why something was done, so the same mistakes arent retreaded. but comments get stale, because they arent tested or statically checked. so always be careful when writing your comments to not make more assumptions then necessary.

Prime, I gotta say, you react in the best way possible. Your commentary and support for the creator are top notch.

"The compiler does not read comments, and neither do I." - Bjarne Stroustrup

I like the idea of commit message as a comment defining why that line was changed and when, and how it looked before and potentially linking to issue that defines a problem and how it was discovered ....

4:18 ehehe, coming from C# I used to be, but since that seems to be the naming convention in the c++ standard library and the language in general, I just adopted it with the argument that consistency is less confusing.

I start with piles and piles of comments because my code usually starts out as a steaming pile. The first write is usually a single file in a single night with 4 cups of coffee, with 400 lines of code and 500 lines of comments. Then comes the first refactor, and the second refactor if it's real serious. Now I have well-structured, lightly commented self-documenting code. In the end I try to keep my comments to primarily just refs/links to outside resources like business rules the code is implementing.

I remember one of my first programming projects at community college in like 2007. Now, this instructor was like a SUPER nice guy and really square like a Mr. Rodgers or Bob Ross or something. Well I was working on the project and got stuck with something and got SUPER frustrated and put in some VERY profane language in the comments at the time. I thought I had deleted all of them. When I finished it and turned it in, he handed it back to me with errors annotated as well as a comment "please refrain from leaving off colored comments in your code". I turned beet red

"CodeAesthetics ... is by far one of my favorite, favorite RU-vidrs" (1:45). Yes! With all of seven (7) videos, each one a masterpiece, we can only hope for more.

Tom’s a genius confirmed

I like using comments to jot down notes or to organize my thoughts tied to the surrounding code, but as I implement the notes/ideas, those comments get deleted because the code basically becomes the comment

If you are implementing something complex, especially if it is something that requires you, the programmer, to remind yourself how it works via stack overflow or wikipedia, you should comment it. At the least, you should include a link to the source of the algorithm. Then, if the algorithm has multiple steps in the wikipedia pseudocode or what not, you should note where you are starting each step. There is nothing worse than having to come back to some Vector3 trig functions because of some slight change in the program requirements, and then spending several hours re-learning something you haven't needed in a year.

I think it depends on the what the code is going to be used for. If you are a noob and learning, explaining what you are doing is helpful. If you are writing code that will be used by a novice or non programmer then the more description the better. In an academic setting were your code is likely going to be looked at by scientist who are weak on skill comments describing what it is doing is a good idea.

Waiting for the Tom's a genius merch. There's your startup.

Thanks for the info!

Long live Tom. Tom is a genius!

I am just wondering, If comments were not writent that bad how easy would it have been to train an AI to understand code ?

Comments are meant to document intention. A well-placed paragraph can obviate the need to read and understand hundreds of lines of code.

Naming things with the code is better than comments, because the compiler checks you. Actual comments can be plain wrong and you only figure it out after you've been confused. And that's the opposite of what the comment was for!

i use a plugin "comment anchors" to name and mark sections of code so i can quickly jump to whatever block i want

3:04 Human hability of choosing some two random values: 77 and 69. 7:01 C++11 optionals comes from boost::optional (introduced in boost in 2004). If you mean the origin of optional has a "programming idea", not sure, but it's an idea that comes very naturally. It's very likely that a lot of companies and even personal projects have introduced some kind of "optional" type from themselves years before boost.

I lowercase the first letters of names of structs and classes but I also put all of them into their own namespace and if a data structure gets too large to necessitate a distinction then that struct/class is (probably) too large in scope

I work in a team where the majority of members have very little coding knowledge, or desire to learn. However, I write a number of Python scripts to support various tasks which occasionally need to be edited/slightly modified by other team members. In this situation are heavy use of comments the way to go? The ideal solution is to upskill the team, but that's never going to happen as the company doesn't hire for coding skills or enthusiasm, and as almost all coding guides (quite rightly) assume you work within a team competent in coding, I feel like they always need heavy adaption to be relevant.

This made me realize that I have a bunch of, what would be considered, redundant code but I don't want to remove it because the human language helps me understand at a glance what the code is meant to do even if that can be surmised by reading the code itself. It also helps with bugfixes if the code doesn't do what the comment says it's supposed to do, the original intent is preserved (though that means I need to update comments when making changes).

I agree. Don't describe what it does but possibly why it exists.

My rule for writing comments is that comments should describe why the code is there, not what it does.

i ususaly have lots of comments, because before coding i usually write a pseudo algo of what i need to do so i can organize my thought... and i tend to just leave them

as a noob to coding i try to comment often. half is for exclamatory stuff and half is for memes. It's a wild realization that you probably don't need to comment on stuff that is self explanatory lol.

Sometimes you have to use libraries that have such convoluted interfaces and unintuitive names your code will become unreadable just due to that. In some languages that includes the standard library..

I always use the comments to set the conceptual idea of the code or logic that follows not the details of whats happening inside the code. So i read one line instead of 10 or who knows how many more(vomit)- like a function but at a higher abstraction. I'm lazy

For me it comes natural. I just put down what I think will be useful to know there. It's like writing notes on paper. I just write stuff that I think will be useful for me in the future. That can come in different forms.

More often then not there are multiple ways to understand what function is doing, a comment should clarify that. For instance GetDescendantsOfType should have a comment telling you 1. whether this is recursive 2. which types are okay. 3. What is the stop condition? Is there a situation where you don't want the recursion to continue? You don't want to sift through the code just to find these things out.

Closing li was required just to make html compatible with XML. In html it was and is required only in specific cases.

Who needs optional anyway! A nice raw pointer can do that with null for unset! Or roll your own optional template class that wraps a raw pointer for fun!

I think comments should only accompany extremely weird solutions that go against conventional logic for whatever reason.

I agree... whether you comment "add 1 to x" or "compute the sum of the vector", the code already makes that obvious. But if you do some strange loop where you're adding +1 for indiscnernable reasons to some index and add a comment explaining how the data is layed out, that actually helps in understanding what's going on. Example I recently wrote, I had two loops, one going over odd indices, the other over even indices and they had a branch where some index was either i, i+1 or i-1 - you wouldn't know what the fuck is going on there without knowing the data layout, "positive" directions where stored at odd indices, with their corresponding negative direction stored +1 index away, and the algorithm implemented there required you to handle those separately and sometimes access those corresponding directions. It was all low-level CUDA code, so no super fancy abstractions. Comments are much more important when you really can't use abstractions like optional but *have* to work with just integers, low level data types and specific weird layouts and giving some weird meaning to specific values, like the -1 in the example. If you're implementing some very specific algorithm, a link to the paper or the name of that algorithm as a comment makes sense. Nobody knows what a fucking esoteric pull is supposed to be or how it works after all.

I comment what a piece of code is doing all the time, but that's more about me learning and having not the best memory. So I can basically reference my own code like classroom notes

Keeping it close to the code is a good idea. Your header files, specifically, should have actual specifications about the inputs, return value, and exceptional cases

moving the condition to it's own function seems like best practice for me

I’m 40k lines into a game and so far the only real comment I’ve felt compelled to write is an outline of the pathfinding algorithm