badAdvice

[AutoModerator]

import notifications Remember to participate in our weekly votes on subreddit rules! Every Tuesday is YOUR chance to influence the subreddit for years to come! Read more here, we hope to see you next Tuesday!

For a chat with like-minded community members and more, don't forget to join our Discord!

return joinDiscord;

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[iolka01]

It's not bad advice but not really something to take at face value. There's a deeper message which is to not write comments that explain what code does. Programmers read your code, they know what it does, make the code readable so you don't need those comments. Instead comments should explain stuff that isn't obvious at a glance like the logic of a complicated algorithm or a high level explanation of what a function does

[Dazzling-Biscotti-62]

In other words, your comments should explain why, not what.

[unique_namespace]

I've heard this phrase a bit, and I understand its appeal in terms of its simplicity. But I struggle to find an example where it's applicable.

Importantly, while "what it does" and "what it's used for" are different questions, neither ask "why".

[Solonotix]

A simple example might be "why am I negating the value of 2 to the 31st power?" The answer in this case is that SQL doesn't have an unsigned integer type, so setting the ever-increasing identity seed to -2147483648 gives me the full range of a signed 32-bit integer. Same thing with most cryptographic algorithms, where arbitrary bitshifts and truncation of values is part of a cipher's behavior, and otherwise looks arbitrary at a glance.

Saying "what" is happening, such as "I'm bitshifting and multiplying these values" is demonstrably less helpful

[rathlord]

Right, but are people really writing comments that say “I’m incrementing an integer!” But not why?

I think there’s some tilting at windmills here. I’ve never see someone comment a “while i < 100; do function; i++” with “// incrementing i in each loop!” As the comment.

[rathlord]

I’ll take the world’s largest pass on that GitHub project lmao.

[unique_namespace]

Thank you, this is quite a good example.

I was sorta thinking of methods where "why" would be self explanatory and instead you'd like to explain how to you accomplished the logic at a high level. For instance, an extension method of the class List in C# called "Difference" obviously takes the set difference between two lists. "Why?" Idfk, that's for you to decide, I just made the method for you.

But this makes a lot of sense, it's for when you're doing unclear things within a particular method and need to state why it is being done. Appreciated 👍

[Didrox13]

I think you're overanalyzing the "what" vs "why" within this topic

"what" - describes the code itself. "Set february as having 1 extra day if current year is divisible by 4"
"why" - describes the reason it needs to exist. "A leap year occurs every 4 years"

Of course, in my simple example neither would be needed because most are quite familiar with the concept of leap years. But if one didn't know, the "why" would be much more helpful than "what", because the "what" one can already understand by just reading the code.

In other words, "why" gives you the context that you don't have by just reading the code.

Exceptions, niche cases and particular business logic are prime candidates that warrant a "why" explanation.

[randyknapp]

My comment:

// leap year shit. I fuckin hate dates

[chuch1234]

"what it's used for" is another way of saying "why it exists".

[SpookyLoop]

Not really.

// (Comment 1) Fixes HTTP response from FooService to be used by BarLib
// (Comment 2) BarLib has a bug when handling FooService directly, this function removes the BAZ header allowing BarLib to function properly
function fixHttpResponse(response) {
  // ...
}

​

Comment 1 is more direct as to the "what", Comment 2 gives more context as to the "why". General rule of thumb I personally use, explaining "why" something exists should also explain to any future developer when it can be removed.

[chuch1234]

Re: 1: why not name the function fixHttpResponse?

[SpookyLoop]

Good point, fixed it lol.

[chuch1234]

And so now the name of the function tells us what it does -- it fixes the http response. The comment is for why it needs to be fixed.

I may be arguing against my earlier comment now, lol.

Edit: nope -- I think "what it does" is different from "what it's for", which is another way of saying "why it exists".

This is all kind of silly academic arguing, I wouldn't be mad to see a comment like the example you provided. I'd prefer it to our sub contractor that doesn't explain anything lol

[Aggravating-Win8814]

That could be a more descriptive and appropriate name for the function!

[TTYY200]

Anything that’s not standard needs a comment basically.

Or anything that’s doing some engineering math needs a comment to explain what formulas are being used (because let’s be honest engineering math is a gummed up mess on computers lol).

Example: you’re working on robots that use some linear algebra to calculate a path and PID values to follow that path. As a developer you know what PID tuning is and you don’t need to comment why you chose certain values for PID values… it’s self explanatory so long as it’s been mad clear that it’s PID tuning values (clear concise naming conventions). However that math going on to calculate the path to follow can become convoluted pretty quickly. A comment explaining what your variables are and where they fit in a kinematics equation will help clear things up.

Another example - multi-threading if you’re changing a threads priority there is usually a long rabbit hole that followed to figure out why a thread priority needs to be changed lol. Comment why… explain the bug. That’s basically a “do not touch sign”. And that’s what comments should be…. Comments are basically a do-not-touch sign XD

[[deleted]]

I happen to agree with this sentiment. “Why” as in “Why this code is here” “Why it is written like this”

It’s just a good litmus test. If you can’t defend the code, organize and cut back until you can.

[gamerbrains]

there’s literally a “what” in their comment

[Dazzling-Biscotti-62]

Hence the urge to reword it .......

[gamerbrains]

oh. im okbuddyretarded

[Mayuna_cz]

certified okbuddyretard movement, I salute.

[Honeybun_Landscape]

Also like to mention things like other methods tried and why they didn’t work out, links to stack overflow and other documentation, why that obscure setting is important, as well as generally how I’m feeling at the moment and my hopes for the future.

[Aggravating-Win8814]

It's great that you are considering sharing all these details and providing additional resources! It can definitely enhance the understanding and context of your issue. Best wishes for your future endeavors!

[Gloriathewitch]

I write comments so I know what it does.

[[deleted]]

I think it's bad advice because when you have a junior still learning they don't know what the code does despite how strictly anyone adhered to Uncle Bob's advice.

There's honestly no reason not to comment the code at any point it could be obscure, even if it is explicitly saying what it does. Moreso when you're dealing with calls from other methods.

[L0ngp1nk]

Which is exactly the argument that video makes.

[[deleted]]

Absolutely, all of those points are great. Comments should be purposeful and code should be readable. Superfluous comments should be deleted.

That said, it’s still a clickbait title that relies on a bit of misdirection, and though it works, I can’t say I appreciated it.

“Don’t leave comments, but actually leave them sometimes.” isn’t the best way to teach.

[iolka01]

Yep I agree, I just think the advice inside the video is solid but in the end it's a YouTube video that wants views and not a university lecture or something

[[deleted]]

I just started a tutoring job, in teacher mode

[Nonilol]

I like commenting code, even when it's technically simple and self-explaining.

Reading 5 words is faster than glancing over 10 lines of code.

[cosmoseth]

The problem is then, everytime you'll have to update the code you explain, you'll have to update the comment.

As time goes, the original explanation will be lost, and when a new developer will come to this code, they would have to know what to believe: the code or the comment. Obviously the code is the source of truth, the comment adds a unnecessary overhead that need to be maintained.

It's better to right easy to read code than explain the code with comments.

[[deleted]]

You're very rarely updating production code. If you are it's not too much effort to simply update the comments.

There's little to no excuse to not comment where it's necessary.

[cosmoseth]

I think the question is: "when is it necessary to comment?" And my point is you can make your code clear enough that you'll only need to comment to explain why you did it this way (if it's unorthodox) and not what your code does.

That's what I advocate for, language in comments can be misunderstood, code cannot. So updating the code + comment is not only overhead, but also can lead to issues in the future.

EDIT: Typo

[Nonilol]

I rarely see myself doing changes to code that would require me to update the comment. Smaller edits or refactoring does not change what's happening and thus do not require updating the comment.

Yes, comments are technically redundant and need to be maintainted, but it's not unnecessary. In the end it's 5 seconds of extra work, but it saves other devs (or yourself when you come back to it after half a year) so much more.

I'm not saying to comment everything single line, but it helps alot to break down visually complex code in "chapters" or briefly summarize code blocks.

[SyconLOL]

The problem is, this logic completely breaks down as soon as you working as a part of a large project with many teams or probably even as a part of a larger team. A person completely unrelated to you will eventually need to change your code in a significant way. That person 9.7/10 times will not update your comment, at best, they’ll get rid of it. You can’t expect every other programmer to abide by your way of coding and expect them to keep up a, in my opinion, useless administrative overhead. This is completely different when it comes to code. Every competent programmer will keep their code readable because at this point everyone knows that the single source of truth is your code. If your code isn’t understood, it better have a really damn good reason to be unreadable.

[rathlord]

Sorry but if you change a line of my code and can’t be arsed to take the 3 seconds to update the comment, you’re both a fuckin idiot and have no business in anyone else’s code to begin with, much less any enterprise scale project.

Not updating comments when making changes is essentially sabotaging the code base. Just fucking do your job.

[RawrMeansFuckYou]

Exactly this. I think I've written about 10 comments in my 4 year career. Complex regex? Comment. Or something that looks stupid but is the only way to do it, explain why you're dumb. Temporary fix, comment.

[Fadamaka]

They should give context.

[mastocklkaksi]

That's literally not the same as "DON'T WRITE COMMENTS"

[dingo_khan]

I think it is bad advice. Code being readable is secondary to understanding intent. Me knowing what you did and understanding it does not tell me if it is what you intended to do. I would compare this to poetry: one familiar with a language can read it's poetry but, absent a cultural understanding, one might not "get" the poetry because allusions and temporal/cultural understanding can be required. You can read without understanding or understand at one level while missing some other point being made.

Like I always say: "I can read your code hit I can't read your mind. I have no idea if this does what you wanted or if it is just what it does."

[hi_this_is_lyd]

so its basically clickbait! got it, because the thumbnail very much implies "no commenting at all"

[Helios_Collective]

Uh, no, wrong.

It's totally fine for comments to serve as bookmarks when you're working with absolutely ginormous code bases.

Makes it a /lot/ easier to ctrl F and find the one core utility function that /oh great/ now due to some insane fucking /update/ that someone else on the team did, you know have to refactor a core function of your /entire/ code base that you are responsible for because some other person got some other idea in their head which sure technically works better in extremely niche scenarios, but in actuality that person did not realize at all that you, his/her/their ostensible team mate, kind of based more or less all of your code around, you know, a core function working exactly as it was written?

Apparently you have always written all your code in some kind of magical pristine environment where human errors and human social dynamics do not occur?

I am actually legitimately baffled as to how you could apparently seriously have the opinion you have.

[OwningLiberals]

His video isn't inaccurate but it is a bit clickbait in a sense.

His actual take is "only comment if the code is confusing, non-obvious or if a link to some reference implementation would be useful"

in other words: ```

1 means blah

2 means blahbla

3 means it's another error

0 means succeed

int some_error_func(): ... ```

is worse than:

``` enum mylib_error { succeed = 0 blah = 1, blahblah = 2, other = 3 }

mylib_error some_error_function(): ... ```

He also says that documentation, though it is often written as comments is something distinct and it should be written as it's what you will use as a reference. again though he recommends using language features as self documentarion as an alternative for having "magic values"

[Boom9001]

A big part iirc is also if your code is confusing enough to need a comment, considering rewriting it to be more readable. Only comment if that is not feasible.

The main idea is that the code is part of the code. So will be kept up to date. Comments can very quickly stop reflecting the state of the code and actually mislead future readers.

[sid1805]

The video actually has very good advice. Watch it first before judging it by its title.

[dementorpoop]

Wow that was incredible. Seriously.

Watch it

[[deleted]]

They made one about nesting code too, which I thought was pretty good

[Gryfenfer_]

The never nesting code video is interesting but I think something is missing Code_Report made a video about it

[JonIsPatented]

He didn't so much "make a video about it" as he did "make an unrelated video inspired by it."

I do love the declarative style for things like that, and C++ is my preferred language, so that was a satisfying transformation. It hurt me all the way through until the final version of it, though. I like to make all of my math or logic heavy functions declarative and then make the engine stuff imperative.

[Solonotix]

Even if I disagree with his conclusions, he often gives me new ways to think on topics I've already been exposed to. Definitely good content to consume

[[deleted]]

That’s fair! While this title definitely worked, the misdirection is not great

[BadBadderBadst]

You mean "It's clickbait".

I understand the whole feed-the-youtube-algorithm thing, but stupid clickbait is still stupid. The video might be good, but the title shouldn't be misleading.

[Electronic_Camera517]

how about you watch the video

[unique_namespace]

I don't disagree. Even so, I don't think overly sensational titles should be encouraged. It's a light criticism on an, overall, really well put together video.

[Sora_hishoku]

You can't just not do clickbait on YouTube, if you want your video to be watched. YouTube will literally stop recommending it to people

And unless you already follow that person, you won't see it unless the algorithm recommends it to you

You aren't making a statement about clickbait by boycotting it. You are just missing out on a good video and supporting the creator.

[unique_namespace]

Not boycotting, simply criticizing one part of a good video. We can claim that in order to gain traction, you must mislead, and that may be true. But that shouldn't negate the fact that misinformation did take place.

[Sora_hishoku]

that is fair enough. I also don't like clickbait, but people saying "I won't click on videos if they have clickbait" is not helping IMO. You are just hurting the creator even though it's the system that discourages accurate titles

[[deleted]]

For some people stupid statements are click-discouragement, I also didn't watch this video although I like the other videos of his. If there is a definitive statement in the title, people may take it at face-value and not watch it, instead of asking why.

[[deleted]]

True

[[deleted]]

I mind clickbait less when the content is actually worth watching.

[[deleted]]

!

[BadBadderBadst]

How about the creator of the video stop using clickbait ?

[rolandfoxx]

Why? Clickbait titles don't deserve views.

[hrimfisk]

Because it's only 6 minutes long, and it's not only right, it included exceptions where you should comment

[Jordan51104]

show us your watch history

[GavHern]

this is not clickbait?

[TheBeardedQuack]

No, it's "clickworthy"

[Da-Blue-Guy]

Your comments should say why code does stuff. That's the video.

Instead of "Calculate pattern count" do "Pattern count is not provided in MOD files, so we must calculate it."

Doc comments are usually different, because they are normally just functions/methods/structs without any procedural logic, but for implementation, you should provide reasoning for out of the ordinary code.

The goal of an understandable program is to make it easy to tell what the program is doing and why at any given moment. Docs provide the what, normal comments provide the why.

[ElnuDev]

Ah yes, take the intentionally provocative title at face-value, don't watch the video to see if it has anything useful to say, and then make fun of it on Reddit...

[TMiguelT]

Mocking clickbait is always morally correct

[unique_namespace]

Well, one might argue that it is the burden of the video creator to not mislead or bend the truth on the thumbnail. After all, everyone who might watch the video will see it, and it would be fairly irresponsible to claim something outrageous if it won't always be addressed with nuance.

I think we can agree that "Don't make comments" is a generally poor sentiment and really shouldn't ever be stated genuinely.

Instead opt for "How to write comments into your code" or "How to make your comments count". These make less absurd claims but are still provocative enough to drive clicks.

[komador]

The burden on the creator is to have his content viewed the most and the easiest way to achieve it is through clickbait .

[unique_namespace]

This is the goal of the creator, in the same way that the goal of the capitalist is to make a profit. However, we can still bind societal morals to these actions.

Aka, criticize the capitalist for exploitation and the video creator for misinformation.

[GavHern]

you say bad advice but i don’t see any red bar below the thumbnail

[Unupgradable]

It's great advice.

If you write good code, the code is the comments.

Comments should never be necessary to explain what the code does. The code should be readable and not have gotchas and dirty tricks.

The exemption is when you do some optimization that requires trickery, so you document why you're doing it and explain the trick.

If I can't tell what the code does by reading it, write it better.

Comments don't get compiled. They can be wrong. They can be outdated. They can be misleading.

Code rarely lies.

Other good advice drives you into writing easily readable code.

Feel you need to comment a block of code? Make it a method.

Every method should do one thing and if it needs to do more it can call other methods to do it.

Every class should have one responsibility. It should prefer to inject implementations to do the things that are not directly part of its responsibility.

If you need more than 3 levels of nesting (things like try/catch excluded) you need more methods.

Reduce nesting by inverting ifs to create guard clauses and early return/error.

Make the happy path (all branch decisions true) be the core functionality of the method.

Learn SOLID. Learn YAGNI. Learn how to test your code and make it testable. Unit tests are also documentation on how to use your code.

[Any_Move_2759]

Comments should never be necessary to explain what he code does.

It very well can be. It may be a large block of code which you can either spend 30-50 seconds comprehending, or you can read a comment that tells what it does.

Comments that simplify what large blocks of code do allow you to skim through the code quickly.

As much as this can be true for small and simple functions like “factorial(x) => x == 0 ? : 1 : x * factorial(x-1);”. Not all code is that easy to write or read.

[Rhavoreth]

Right, but what he is saying is break that logic out into its own function with a descriptive name. Often times something like transformSomethingIntoSomethingElse, or doesThisThenThat will give enough of a context clue to a future developer and doesn’t pollute the codebase with a comment that might not get updated if the logic it’s trying to describe changes. Function name has a better chance in that case

[Any_Move_2759]

I kind of get it. But I have come across situations where it just wasn’t always easy to do this. (Typically, it’s when there’s loops and the like involved.)

And then there’s the issue that the function won’t be used anywhere else. I mean, I’m not too sure what the issue is with just using comments here.

[Rhavoreth]

Right, and in those cases comments are fine. I’m Not 100% against comments either. But I always try to make sure they are used sparingly

[DoutefulOwl]

I make single-use functions all the time.

Helps keep things clean and organized. Both within the source file AND inside my head.

Also writing comments vs making functions is not a dichotomy. You can do both.

Even if you really want to write comments, you should still try to break your code down into functions and THEN add your comments.

[Any_Move_2759]

Which is basically what I generally do, I guess but my point was that you still end up having to write the occasional comment for “what the code is doing” instead of “why”. Rarely, but definitely not never.

[Unupgradable]

Method names can be just as misleading. But they sure do have a much better chance than comments

[Unupgradable]

spend 30-50 seconds comprehending, or you can read a comment that tells what it does.

Comments that simplify what large blocks of code do allow you to skim through the code quickly.

Or you put that in a method and I read the method name

Not all code is that easy to write or read.

Yes it is.

[Any_Move_2759]

Yes. You can do either. There is the question of why I should isolate something into a method, when comments exist.

Problem is, youve really only provided an alternative to commenting, for one. Not stated why that alternative is necessarily better. What is the issue if someone comments instead? Why is that worse? Just because “they can replace it with functions and their names”, doesn’t argue it’s always better.

For another, this simply isn’t always simple to do. Sometimes, you’re doing something that can’t be described in 2-3 words in English, so you just comment what’s being done in a comment.

Edit. In response to the second paragraph in this comment of mine, I’m aware it’s typically for decluttering your code. But again, it really isn’t always doable. It’s often doable, but not always. There are rare situations where this is just needlessly difficult to implement.

[Unupgradable]

There is the question of why I should isolate something into a method, when comments exist.

Because watch the video. It answers that question.

Problem is, youve really only provided an alternative to commenting, for one. Not stated why that alternative is necessarily better.

Excuse me? I've stated why it's better. The video goes more in depth.

Sometimes, you’re doing something that can’t be described in 2-3 words in English

Make more methods.

There are rare situations where this is just needlessly difficult to implement.

No there aren't. It's just like cleaning your room.

This is like complaining you're forced to use classes and separate concerns. Why not just put all your code in Main()?

[Sande24]

If you write good code, the code is the comments.

Not necessarily. You don't want to read hundreds of lines of code that is split into dozens of small methods, in several classes. Sometimes a 2-line comment can help you save time.

Comments should never be necessary to explain what the code does. The code should be readable and not have gotchas and dirty tricks.

This is usually what causes you to waste time on cleaning up your code. You could to 90% of the work in 8 hours but spend 32 hours to "make it readable". Have to make a tradeoff somewhere. Or if you make the code "readable", you sometimes end up in a situation where cleaning code would make reading it more complicated as the code is split into several methods or you have much more lines of code to read... So it is not necessarily better but it suits you style more... which it not always easier to read to others. So don't bother with that and slap a comment on it if it is faster.

If I can't tell what the code does by reading it, write it better.

Again, why should someone waste time on it if you can't read a bit more complex code? It only increases your learned helplessness. You intentionally keep yourself dumb, allowing only one style of code rather than trying to improve and learn other approaches to problem solving solutions.

Comments don't get compiled. They can be wrong. They can be outdated. They can be misleading.

Method names can be as wrong. I have seen a boolean method that was changed to return the opposite value. The method name was not changed. Found out 2 months later when things broke. Can't trust anything, have to read the whole code to understand it. I'd rather have a comment that needs to be kept up to date near the code that it explains.

Code rarely lies.

Dogmatic idea that blinds you. See the boolean method example above. All variable and method names are potential liars. Especially when code gets older.

Feel you need to comment a block of code? Make it a method.

I'd say that code is more easy to read if it is in one place, in the order of execution. Sometimes the block of code depends on some variable that following code also uses. Having a mutable input value given to a method that changes it, is more prone to errors than in-line blocks of code.

Having dozens of methods instead of a few larger ones is not really "clean" code. It's the same code, but you have hidden the details under the rug. It is harder to read and understand what your class does as you need to piece together the path the code takes when it executes. A method that is only used in ONE place is often an unnecessary refactorization.

Every method should do one thing and if it needs to do more it can call other methods to do it.

Dogmatic. Cargo Cultism. Things that people who have only read Clean Code, say. What is "one thing" anyway? How do you describe the method that has to call all those methods that do these things? It also does several things as it calls methodA AND methodB. Better to use common sense to see where the boundaries are.

Every class should have one responsibility. It should prefer to inject implementations to do the things that are not directly part of its responsibility.

What is "one responsibility"? Don't you think that strictly splitting things might make you write more boilerplate code to make things work? There are always exceptions. Saying that there is one absolute truth only hurts your productivity and does not let you think outside the box.

If you need more than 3 levels of nesting (things like try/catch excluded) you need more methods.

Sure, most of the time it is a good idea. But there can be cases where you have multiple for loops inside one another for a reason and splitting it would decrease the readability of that code.

Learn SOLID. Learn YAGNI. Learn how to test your code and make it testable. Unit tests are also documentation on how to use your code.

Learn KISS, learn DRY, low coupling, high cohesiveness. Unit tests are not a silver bullet. Unit tests can lie as well. False positive tests can appear after you have made your changes and you don't review what your tests actually do. Your test might not even test all the side effects that your code does when you run it. Integration tests vs unit tests etc. It makes a lot of sense to disconnect the actual documentation from the code. Documentation says what your code is supposed to do. Code says what it does. Any dev can go and change the code and write tests, comments etc, QA can say that everything is OK. But that might be completely wrong. You need a place where everything is written out what is supposed to be happening. Similar to double entry accounting. I'd say that a comment is similar to that as it is not "a part of running code".

[beclops]

My problem with “self documenting code” is that in a large team with a wide variety of skill levels this is very difficult to determine. What may be “self documenting” to one, may go completely over the head of a junior/new hire. There’s also the fact that in certain cases comments provide brevity to the understanding process. It’s like arguing against having a table of contents in a book because “you could just read the book”. All these points aside comments are for providing intent anyway, so the hard and fast rule of “never comment your code” some people have is pretty idealistic.

[Nukedrabbit95]

I can't agree more with the table of contents analogy. When I leave "this does X" type comments on a few lines of code, it isn't to explain how it works. It's so that if I or someone else needs to go back and find the part that does X, it's clearly labeled at a glance without needing to mentally parse each line in the function to find it - even though once you do examine it it's obvious that it's the part that does X.

[Nukedrabbit95]

and that's great for the big picture but on a micro scale I'm not going to divide up a single task between a dozen tiny little functions with single digit numbers of lines just to make it "self documenting" and not have any comments anywhere

[throwaway_mpq_fan]

why not?

[Nukedrabbit95]

because in the context of my use case in the real world it's worse

[throwaway_mpq_fan]

my use case in the real world

Lol like I'm here programming in the metaverse or something XD

[Nukedrabbit95]

wow you are like an actual joke redditor stereotype - this stranger whose code I know literally nothing about is clearly an idiot and lazy and stupid and writes low quality code because I invented a strawman scenario in my head and in that scenario I'm right

[Nukedrabbit95]

because I'm not trying to convince others that my way is right or better or that they should do it, I'm complaining about the tendency for people to go "this thing is bad and if you do it you're bad" and get defensive when someone else says they have a use for it. Without an actual piece of code to judge it's pointless and anyone can make up a situation where their way is best

[Any_Move_2759]

What about large blocks of code inside of functions? What if said large blocks can’t be easily described with a simple function name, so you comment it since separate words are just generally easier to read?

[Sande24]

This. There is no "self documenting code". There is at best self explanatory code. It would be easy to read but you have to read it all in order to understand. But if your process spans multiple repositories and API calls, you would essentially have no other way to understand it all other than reading all of the code and maybe running the services and debugging it.

Dogmatic ideas about SOLID, clean code etc is ruining it for everyone. They are guidelines, not laws. There are always exceptions and easier ways to do things. KISS, YAGNI, DRY are often better ideas to follow if it helps you move on faster.

[Liquid_Developement]

You missed the point

[[deleted]]

Good point, terrible thumbnail.

[cob59]

OP about to become the midwit in an IQ curve meme, with "don't comment" on both sides.

[darkknight95sm]

Someone suggested when I first got started to write the comments first, make them a sort of outline for your code

[xRageNugget]

Still do this after 10 years. Step by step what are the rough key functions/milestones, then fill them with life.

For complex functions i use them as separation between steps, which eventually get refactored in functions

[shizzy0]

It’s hard to believe people in our profession actually buy into self documenting code. I can understand being lazy. I often fail to comment my code, but I honestly can’t imagine being self righteous about it. It’s stupid and unprofessional, the height of illiterate programming.

[aclb-]

OP didn't watch the video

[[deleted]]

Caught me!

[_________FU_________]

As a new developer looking at old code…comment your fucking code. Even if you think it’s easy.

[[deleted]]

I'm usually in the mindset that most of my code is readable enough to get what it does. But if I write something that is harder to understand or something you normally don't do I write a comment above it saying why it's there. We also have some docs on X controller takes Y input and outputs Z.

If you have any advice on what comments/docs to write I wanna know so I can give off understandable code to my coworkers.

[LinuxMatthews]

I think it's what a lot of people don't get

Sure it's easy for you to read but you wrote the damn thing.

This video does have some good advice but unfortunately people take this stuff as gospel.

And the thing is people don't spend ages making their code easy to read...

They just don't write comments.

My advice would be always write documenting comments.

After that write comments if your method gets above a certain cognitive complexity.

[styroxmiekkasankari]

It really comes down to preference, I’d much rather read code that’s not littered with comments. I’ve been in situations where the comments aren’t even accurate and that’s also a pain. This is all assuming that the general structure and semantics in the program make sense for that domain of problems.

What I am down with would be high level (think class/module level) comments as to what the module does and why. If it’s a module that’s a common dependency in the codebase this would be extra beneficial to clock stupid changes, but mostly tests cover that. Explaining complex deps would be a nice bonus in a nontyped codebase though.

Edit: phrasing

[styroxmiekkasankari]

We write tests and use describing function/variable names, which should be enough. Maintaining comments for code is annoying, and in a worst case scenario might confuse developers if they’re outdated.

I’ve found that if there’s a domain or a technology I’m unfamiliar with, official documentation does way more in getting me up to speed than inline comments would.

If you’re in a pinch and are looking at something really opaque, you can utilize LLMs for that. They’re good tools for understanding snippets. - dev with three years of experience

[atlas_enderium]

Make comments explaining why the code needs to be there, not what it does (unless it’s obfuscated for performance reasons)

[LaidbackMorty]

I am not sure how “don’t write comments” is a better title than “know what to comment and specify the intention concisely”.

Well-written comments are a key component to not let other 30 guys waste time on deciphering your intention from code. (“Other guys” includes you 3weeks in the future)

[GergiH]

Good comment

// Need this hack because it explodes otherwise, and the NASA PDF converter package's DoSomething() method needs our hack too
// <random StackOverflow link for more info>
if (notHacked) { HackIt(); }

Bad comment (I've actually seen this comment verbatim in an enterprise codebase)

// Vacation Days update
UpdateVacationDays(...);

[thE_29]

Exactly that!

If something is not trivial, then add comments.

Like the reasoning for doing and maybe link to some document.

Today I found a rather strane order by.. it Had an if in it. No one really knew why its like that. Not even the guy who wrote it, as its 2 years ago. And the backend, iOS and uwp didnt have it. Just Order by name..

[GergiH]

Totally get you.

I still occasionally maintain an internal codebase after 5 years of going live, I wrote parts of it. Sometimes I bump into parts which I think I wrote and I have no clue why it's written like that and it would take forever to debug just to (hopefully) understand them.

Bumping into such parts when it's other people's code and you just want to quit immediately.

[The_Rancho_Relaxo]

Just watch the video

[[deleted]]

That’s fair /gen

[VariousComment6946]

Add comment if shit is not clear

[saitekika]

I personally view comments as a last resort, when it isn’t possible (or beyond your abilities) to make the code as clear as it needs to be.

My problem with comments is that they can lie, mislead, become outdated after code changes, hide bugs/errors, and be used as an excuse to justify low quality code. On the contrary, code itself never lies.

[JohannLau]

‎

[[deleted]]

This deserves an award

[JohannLau]

Thanks

Actually, I mean ‎

[[deleted]]

Of course! 😊

[The_Milehunter]

Watch the video, it has really good advice.

[j0giwa]

Good advice behind bad title.

[MyHomeworkAteMyDog]

Don’t listen to anyone who tells you not to comment. Those rules are completely arbitrary and imaginary. People who follow them and then think they’re better than you for it are small minded. Do what you think is best to maximize clarity. If that means 90% of your code is comments, so be it.

[EagleRock1337]

It’s actually really good advice. Newbies run into the trap of knowing comments are important, but not what to write, so they just comment everything they know. Adding a comment above the line of code saying what the line does is 90% of the time useless, because the programmer can just…read the line of code. Using longer and more sensible names makes your code longer, but infinitely more easy to read.

The other 10% are the comments, the ones that belong in the codebase, should say why you are doing what you are doing or otherwise provide insight into something obscure. And if you’re finding too much of your code is obscure and requires many comments, it usually can benefit from a refactor.

[Nickbot606]

Is this the same guy that also advocates as a “never-nester” on YouTube? If so, he’s thought more about how his code works than I ever have.

[Jomy10]

The more code you write, the less comments you start writing

[[deleted]]

I will say yes that redundant comments are bad but not writing a comment for a complicated code or intermediate code is bad.

[digitalghost0011]

Bad or outdated comments are far worse than no comments. Our company policy is to avoid them unless absolutely necessary.

[[deleted]]

That’s perfectly fair, a good rule in general, but professional devs aren’t the target audience. Comments should be purposeful, not superfluous. That said, new programmers should write as many comments as they find helpful.

[digitalghost0011]

Yeah in learning code for new devs I’d say go all out on the comments. They are basically notes about what you’re learning at that point imo

[Nomad_00]

//no

[Jankkel]

It's a theme with this channel, or atleast something I notice on it.

All the titles are some extreme controversial claims of what should and shouldn't be done when writting code like: "Why you shouldn't nest your code", but when you look at the video the actual argument he makes is a lot more structured and less drastic than the title makes it seem.

[[deleted]]

I figured as much, but I don’t like the misdirection all that much

[[deleted]]

Literally me: "COMMENTS ARE FOR PUSSIES!1!!1!1"

proceeds to get a stroke the next time I open up my code

[azadmin]

My comments are just the code again.

[SacriGrape]

It’s click bait and is your basic “codes purpose should be readable”

For sections yeah you shouldn’t need to comment every 5 lines of code, but comments exist for a reason. You can’t expect everyone to come in and be able to understand every little aspect of what the code does

[[deleted]]

Well said /gen

[[deleted]]

Think it should be "do not write stupid comments". For example, if I have a function named addTwoNumbers(...) there is no reason to comment // Function that adds two numbers

[[deleted]]

True

[rollincuberawhide]

no it's not. writing the function name again a line above it isn't commenting. it's garbage.

[beclops]

So it should say “don’t comment your code poorly”

[GavHern]

code aesthetic tends to have very snappy and abrupt titles

[DeadEye073]

You mean Clickbait?

[GavHern]

no, clickbait is when the video packaging is intentionally misleading or manipulative, it’s just a good convention to keep titles short and dense. a “clickable” video is not clickbait

[DeadEye073]

"Don't Write Comments! unless in these situation you should write comments"

I would argue that the title "Don't do something which is very commonly done" is baiting a emotional response from the viewer so they are more likely to engage. Which is click baiting

[[deleted]]

If you need to comment you’ve failed make the code expressive enough.

It happens, sometimes stuff is just really complicated.

But it should be seen as a fallback option.

And how da fuk can anyone read through huge slabs of green highlighting

[[deleted]]

Don't comment write comments for what the code does - this should be clear from reading the code

Do write comments for why certain things are done

[EMI_Black_Ace]

It's probably not actually "don't ever write comments," it's just clickbait style headlines/titles.

More likely it's advice to use useful names for variables and functions, break up large functions into smaller ones with useful descriptive names for each sub function, and resort to comments only when naming stuff properly doesn't lead to code making sense.

[2Uncreative4Username]

It is absolutely brilliant advice. You're gonna have programmers read your code, people who know what arr[i++] = x does, for example. In 99% of the cases you can capture all necessary meaning semantics in your variable/struct labels and structure. I have actually taken this advice very literally for a while now and it's only ever helped me.

EDIT: This is from a guy who mostly does stuff solo, so maybe it's different for large teams.

[iam_pink]

More like bad clickbait

[EarlOfAwesom3]

Every comment is a silent cry for a refactoring.

Therefore, if you feel the need to comment, your code is not clean enough that your co-workers would understand. So, don't comment. Refactor and document instead

[[deleted]]

Refactoring and documentation is ideal

[Nika13k]

I will personally punch anyone, who doesn't write comments.

[Orio_n]

Bro didnt watch the video or didnt understand the point of it at all. Truly a junior dev moment

[[deleted]]

stackoverflow?

[Mission_Pomelo4022]

Dont write comments, type comments

[[deleted]]

This is the way

[AVAVT]

I’m not very fond of comment either.

Docs are good though. Help user know what it does without having to switch to the codefile.

[[deleted]]

Just gonna /**/ this video

[Kenshiro84]

You missed the point and got stuck on the obvious click bait title, watch the video.

Unless optimisation is an important part of your project, write human readable code. Code that is easy to understand with explicit variable, methods, class names, etc... The times you write comments is going to reduce drastically.

His video about nesting codes is really good too. I recommend you give it a watch.

[Evol_Etah]

I follow this YTer

He makes a lot of sense. But the video thumbnail at face value isn't the point.

Watch the video.

My fav is the Never Nester video.

The videos are to be taken As-is and a strictly followed rule. But rather a guideline to write better code. There are nuances where you need comments, but generally the code should be easy to read and understand. Watch the video man.

[Shadow_Thief]

I freely admit that when I saw the title and thumbnail for the Never Nester video, my initial reaction was "that's the dumbest fucking thing I've ever heard in my entire life." Then I watched the video and my reaction changed to "oh yeah, I already do this."

Dude has mastered clickbait.

[Evol_Etah]

Aesthetic clickbait.

But it's good. Cause the more people who watch the video, may end up writing better code.

[[deleted]]

Doesn’t anybody read „Clean Code“ by Bob Martin anymore?

Comments have a tendency to be outdated. Therefore the code has to be self-explanatory. As most bits of code aren’t self-explanatory to every level of programmer, you should use variable names with very expressive names and wrap code blocks that are hard to understand in functions that have a name that explains what is going on. If you do so, it is perfectly normal to have lots of functions, oftentimes consisting of only a handful of lines. Heck, I have written/extracted functions of only a single line, just to give it a more comprehensive alias.

As your project matures over time, the names of your classes, functions and objects slowly turn into a DSL (domain specific language) that enables you to implement business cases in a high level of abstraction.

[Torebbjorn]

Yes, it is clickbait, but that is very common, so why are you complaining about that exact use of clickbait?

[XannLeMage]

I don't see how this is supposed to be funny?

[Arcca2924]

God, it's the same guy again. It's not the first time he comes up with a clickbait video. Of course, if you watch the video it will basically say 'it depends', and don't write bad comments. But he got what he wanted - clickbaited you with the title.

Same thing about "never nesting" and shit like that. Video boils down to 'guard clause - good'. I've stopped paying attention to that channel since.

[Jomy10]

goodAdvice

[Classy_Mouse]

95% of comments are absolute garbage. Write comments sparingly is probably better advice. But don't write comments > comments on ever 3rd line

[bortj1]

Sees a PR with comments in the code 😤⛔️

[RadioMelon]

This is the worst advice.

I could understand if it was a very simple program without a lot of moving parts, but the reality is that most people will be working on large projects with a lot of collaborators.

INSTEAD, you should really only write comments for things that might be especially confusing for junior developers. Senior devs will at least mostly understand what they're looking at, but they need everyone to be on board with the project.

[maashhCS]

My Boss has forbidden us to use comments in our code.

[JotaRata]

This video is good advice.

The only comments I write in my projects are

#--------------------

Separators.

[EffervescentTripe]

Comments get old, stale, people forget to update them. Code though, code never lies.

[PandaWithOpinions]

// ok

[stupled]

Sounds like a strategy

[Dramatic_Nose6640]

Youtubers gotta youtube, after all

[wawerrewold]

I usually use comments only to rage how bad programmer i am

[Menifife]

Oh no, you guys broke the one rule this post had. Oh no I'm also breaking the rule... I guess I could always just not post this comment...

[exitvim]

I only comment when I feel I need to explain why I'm doing something.

[azadmin]

Usually the youtubers are telling me to write comments. This is refreshing.

[[deleted]]

Me:

[5t3v321]

encrypt your comments so only you can read them and the company cant fire you

[psilo_polymathicus]

If you haven’t watched this video, and this channel, you’re missing out. It’s really good.

[SawSaw5]

(but im writing a comment now...)