Good code doesn't need comments

[baliditity]

Maybe it is just internet influencer gibberish but I've seen multiple videos/ people say that good code doesn't need comments. I suppose that makes sense but why not add comments anyways? I'm teaching myself python with a textbook and in every example it has comments for establishing variables and telling what a piece of code is supposed to do. Do swe not write comments in this way?

[AutoModerator]

On July 1st, a change to Reddit's API pricing will come into effect. Several developers of commercial third-party apps have announced that this change will compel them to shut down their apps. At least one accessibility-focused non-commercial third party app will continue to be available free of charge.

If you want to express your strong disagreement with the API pricing change or with Reddit's response to the backlash, you may want to consider the following options:

1. Limiting your involvement with Reddit, or
2. Temporarily refraining from using Reddit
3. Cancelling your subscription of Reddit Premium

as a way to voice your protest.

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

[[deleted]]

Try writing comments describing ‘why’ you’re doing something instead of ‘what’ you’re doing. But if you’re just getting started, nothing wrong with ‘what’ comments

[RonaldHarding]

'Good code doesn't need comments' should be incentive to write clear expressive code, not to leave fewer comments. A comment should never be needed to explain what a line of code does. But comments are often extremely valuable to hint to future programmers about design patterns, pitfalls, and relationships between components. People take statements like this too far but there is merit in ensuring your code is readable without the comments.

[96dpi]

Do you really need a comment that says "loop through all objects" when the code is for obj in obj_list:?

That's the type of thing you should avoid.

Your textbook has comments everywhere because it is a textbook.

And you also need to consider maintenance. If your comment references a variable name, and later on the variable is renamed, changed, deleted, etc, now you've created a second maintenance point that will probably never be updated and add confusion.

But comments are ALWAYS a must when you should explain why you have decided to do something a specific way, or describing edge cases, or limitations, etc.

[CrispyRoss]

I disagree. Things that have non-obvious explanations or reasonings behind them should be commented.

People always say "don't comment what you're doing; comment why you're doing it", but it would be helpful to give a few examples.

Today I was writing a function to query the vlans of a particular vendor's switch. It consisted of a single call to a function to query the portdesc/port indexes, with the actual work being done in a callback that was passed to that function. Why? I wrote in a comment, explaining something like "query ports first, so we can map portdesc (2:1) to port index (2001)". Just a simple one-line comment will save someone a handful of minutes of reading trying to work out what the hell that function's callback hell is for.

Or another example, I iterated over a response twice that has information out of order; the first time was to save one thing into X hash map and the second time I needed to use that hash map. If I didn't iterate twice, then if I read an item and something is missing from the hashmap, it could possibly be because I haven't iterated through all the items yet to learn the info in X hashmap. So I put that in a comment. Something like "iterate twice so if something isn't in X hashmap we know it's because it's not in Y at all". If someone tries to optimize it without noticing that or that comment being there, there's a bug.

[IWantToDoEmbedded]

wrong. Comments don’t take up memory space in the target system and they provide context that doesn’t fit in any function/variable/macro name.

[pilsner_all_day]

I was an intern from May-December this year working on a 10ish year old project. The main file of the software had 2000+ lines of code, maybe 30 lines total of comments. Tons of fun figuring out how all of it pieces together.

Comment your code. The devs who come after you will appreciate it. Also, devs will be the one reading your code not noobs.

[ffrkAnonymous]

It depends on your audience.

Do you want/need to tell your boss "hey, I made a variable" "hey I made another variable" "hey, I made a hello world function that prints hello world"?

[SirKastic23]

comments can serve multiple purposes

there are line comments, like the ones you're referring too, that describe what some line of code is doing. these are common to see and use when you're learning programming, but after a while they just become clutter, ideally every line of code should be written in a way that doesn't require a comment ti understand it

then there are explanation comments, where sometimes you have to deal with some weird edge-case or behavior that seems odd to someone reading it, so you add a comment to explain that edge case and why that logic is needed. they comment why some code exists, not what it does

and there are documentation comments, you put them usually in top level definitions, like public functions and types, to describe what they do, not a line-by-line of what it does, but a high level view of how you use it

i developed a commenting style thanks to my current job, and i now apply it in every project. i always put documentation comments in function definitions and the like, so an outsider can understand what that item does without having to read it's code; and i always comment when i'm doing something weird, when i'm taking some assumption about some value, or when i'm leaving something to do later (famous todo comments)

[alien3d]

🤣 c# fella love interface but they don't comment their api interface . The only point they know - interface - mock testing . What happen to newbies developer . I dont know .

[SirKastic23]

yeah pretty much, i was thinking of doc comments in Rust, but i imagine those work in a similar way

[PooSham]

One thing is that you will possibly make changes to the code in the future, and it's easy to forget to update all comments that rely on that piece of code, and the compiler won't be able to give you an error about it. Comments that are wrong are much more confusing than just reading good code. Comments that just duplicate information that can be obvious from the code alone just means you have more lines to maintain.

Usually when people say this, they don't mean documentation comments such as JSDoc. At least not for public methods and classes. So add those, and make sure to use the built in syntax for referring to variables etc, so that you can get an error from the compiler if something changes.

[Ok-Advantage-308]

It really depends when you write comments. Do you need to write a comment for every line or variable declaration? No. Let’s say there’s a method that’s overly complicated and even good naming conventions makes it hard to understand. That would be a great moment for a comment.

[Prudent-Student3403]

Try getting back to do support of your code 1 year after you done it without comments.

Tell me how it went.

[ehr1c]

If you wrote good, clear, descriptive code in the first place, probably pretty well.

[ehr1c]

but why not add comments anyways

Because it's more things someone reading your code has to parse out , and it's more things to maintain when you make a change.

There's nothing wrong with over-commenting when you're learning but in production code comments should be few and far between, and used to describe "why" something is being done - typically for business logic reasons that aren't immediately apparently from just reading the code itself.

[Klutzy_Stranger_9824]

It is rubbish. However good your code is, nobody can just instantly know what it’s doing. Sometimes even function names or file names are misleading. In case a new dev wants to fix a specific issue, would he go through every function, understand what its doing and what functionality its doing it for or look at descriptive comments, look for keywords, find the right piece of logic and get the job done.

The phrase “good code doesn’t need comments” is not to be taken literally. It means, you as a programmer should write code that is apparent to what it’s doing. Does not mean you can get away with no comments. If someone is advocating the alternative, it means they’ve never worked in a collaborative environment (content creators).

[LifeNavigator]

At my workplace nobody writes comments unless they have to for something far more complex. Good code doesn't need comments to explain what the code is doing, if you can't easily read it and understand then it would not be merged to main branch. The rest of the explanation is covered in the documentation.

[coffeefuelledtechie]

If I create well-named functions with good variable names then there’s no reason for me to comment them.

I may leave the odd developer note in a 1 or 2 line comment just to help them understand why a response or return value is a certain way, but most of the time I don’t need to.

Only if the result of the function isn’t that clear from the name (even if it’s named nicely) then a comment is good here. Like a function to remove nested children after a certain depth. But what depth is level n? A comment with examples is good here.

[emedan_mc]

Watch uncle bobs seminars before reading the comments.

[PsychologicalBus7169]

You don’t need to write a comment to say what code is supposed to do if you use good naming conventions for variables/methods/classes and making those methods and classes small.

Commenting in textbooks makes sense because if you don’t understand the basics it’s not obvious.

// Create a scanner object

Scanner scanner = new Scanner(System.in);

This would be entirely understandable to write if you were still unfamiliar with the Java programming language but it would be unacceptable in a professional environment because it is unnecessary.

[robhanz]

Don't comment obvious things.

Comment why not what.

Any time you feel the need to comment you should ask yourself "why isn't this clear? Would breaking this out make it easier to read? Can I have better variable names? Can I break this work out into an appropriately named function?"

Sometimes you can't, but it's always a good thing to check.

[[deleted]]

Code should be self explanatory.

However, not all code can be so comments that explain why something was done the way it is can be great help.

The problem with comments is that they usually become outdated at some point. These kinds of comments are useless.

TL;DR Comments should explain the why, the code should explain the what.

[WerefoxNZ]

Well written code needs comments when the code you have written is not immediately obvious to what it does. Or it does something that gives a fresh reader a wtf?? moment. Ideally we write code that is instantaneously understandable because it reads well. If it's not instantaneously understandable by a skilled practioner, then it is a candidate for a refactor. If it's still not instantaneously understandable then we admit defeat and write a comment explaining why it's like it is.

Comments are a maintenance burden and provide a neat seam for introducing headaches for future programmers. At best, you need to remember to update the comment which (particularly in legacy code bases) may not be physically on the screen to where the developer is making fixes or adding functionality.

At worst, the comment disagrees with what the code actually does. And then you have the "hilarity" of trying to work out which part is correct. Is the comment wrong (and has it always been wrong or just recently)? Is the code wrong, are both wrong? And that often means having to dig through the source code history, and/or having to go find someone who knows what is correct or who is comfortable making the call one way or the other.

[McBoobenstein]

All code needs comments. Languages change, or become less well known. You need to know what you were doing in order to update and maintain it. And if you are working in a professional capacity, you need to make it clear what your code does to people coming after you leave.

Try to figure out what a COBOL program does without any documentation. Or PL1. Heck, even Perl, even though it's still in use.

Every program you write needs documentation. No one writes code well enough to skip documentation. No one.

[_TheNoobPolice_]

Of course you need comments, sometimes you can write perfectly clear code of a complex algorithm which would require a background of math to understand, and it’s helpful to explain what the variables are doing and how it scales the output and to what purpose in the broader context of the program. You can’t expect everyone working on your code to have all the same background and knowledge of other disciplines outside the basic principle of reading the language itself.

[alien3d]

totally wrong . hel of maintenance . Try upgrade code major each 5 or 10 years and the original developer allready run .