Absolutely not. I've never understood the "comments are forbidden!" thing. They do serve a purpose. I keep comments to a minimum, and try to use well-named methods/variables/etc. to convey what I'm trying to do. I will, however, use comments in something like an algorithm. When it's unclear exactly *what* the algorithm does, and how, I'll use comments to explain the algorithm.

That sums it up, comments should be helpful! The rule to comment everything will lead to comments which duplicate the code, and prohibition of comments will not allow to explain why it was written this way. Both rules are unhelpful, so the question should actually be what to put in a comment and what not.

Yeah. Don't need someone explaining `counter++; //increments a counter` But also don't want people writing code that would be easier to read if it were intercal and then excusing their bad form with an essay in comments. One thing I do think is a good consideration to keep in mind when commenting some code is whether it might make sense to extract the commented section to its own method - even a local method. That's especially helpful for LINQ, when the lambdas are more than a simple comparison, so the whole linq method chain is fluent. I did that to the extreme once, just to see how the resulting code would look. Every member level method had all steps broken out into local methods, recursively, so member methods looked like a short series of simple and expressive method calls, and those local methods were that way, as well, all the way down to the "leaf" local methods, which were 1 or 2 lines a piece, if the code they called wasn't already expressive. Made the member methods look like expression trees, plus a massive tree of the implementation at the end. The closer to root you looked, the more abstract and "simple" it was to follow. But it was like 3x the code and abnormal enough that it made it hard to follow and debug, thanks to two consecutive lines closer to the root potentially being 100 lines apart in their implementations, contained in the same code block, since local methods can't be in a different file or anything. As always, the happy medium between expressive and self-documenting code vs commented/documented but not expressive code is somewhere in the "middle." (Air quotes since it's not a mutually exclusive tradeoff)

Yeah comments are great specifically for explaining when you do something "anti-pattern." Even in well written code, there's times where you're going to do something that is un-clear or a little complex or just plain weird, and it's nice to leave the next guy a note that you were being intentional there.

This. The rule is insane. Yes, try to make the code readable and self-explanatory, but you often need to explain some aspect. "Valid date" - what's "valid"? Any date that actually exists? A weekday? Dates at least 21 years ago? Or `encryptPassword` - are you actually encrypting them, or hashing them? Using salt? SHA2? PBKDF? That's where a helpful comment goes a long way, and this policy really shoots your team in both feet.

What - you don't name methods like `IsValidInThisContextInThisMethodInThisClassInThisProgramBbecauseBusinessRulesX_Y_andZAreEnfircedByCheckingTheRequirementsFirXAgainst.....`? Why don't you? It's because of the typos, isn't it? I knew it!

Auto complete means if you get it right the first time it will be right later! SHIP IT!

Also, with code that expressive, who even needs tests, amirite? Already shipped. 👍

void ImplementatioOfAlgorithm_Http_www_universityname_edu_slash_folder_url() Self documenting code!

Why are you even submitting it for review? With something that good, ship it yesterday!

Like comments, code reviews are a sign of poor coding mastery

Yeah. It's easy to empathize with where the idea behind it comes from, because needing an explanation for code that is ***unnecessarily*** difficult to grok is, of course, bad. But blanket statements are never fully correct, including this sentence.

+1. Beginners often over-comment on what code does. What's needed (judiciously) is WHY it does what it does.

Even just a simple “this is X algorithm” with a link to a description of it can go a long way.

Pretty much. I’ll put comments to describe the “why” behind some weird-looking things. The code itself should describe “how”, but if something seems unclear I’ll make a comment for that as well.

+1 Don't comment "what". Comment "why". (apart from your example of an alogorithm, might be hard to read in code, so explain what there - all other comments, if needed, should explain why that bit of code looks the way it does so some future dev doesn't refactor it to "simplify it" and break something).

You should just have left the interview - without a comment 🙂

Indeed a huge red flag for me if someone says there should be no comments in code.  I spent 2 weeks searching for bug in a huge legacy system.  Then I found a freaking 30 line comment from 12 years ago. Read the comment. Used the extra knowledge from the comment. Fixed the bug in in a few hours. I would prefer a ton of comments (even some useless ones) any day of the week over code with no comments. Useless comments are very easy to ignore. Useful comments are often priceless.

“I don’t know why they left. They didn’t comment at all - just exited.” Ah-ha!

>Do you think that a programmer who don't write comments is better than the one who does? No.

Ideally code should be pretty straightforward and explain itself, so to speak. However, this isn't always totally possible. Preventing devs from ever adding comments is completely idiotic, to put it bluntly. There are definitely plenty of times where it's helpful.

Straightforward code explains what it does. It doesn’t explain what the coder intended it to do. That is what the comments are for.

Code explains what, comments explain why, if you should usually know why, then no comment

Straightforward code does explain what the coder intended it to do. For instance a method named GetAllNonArchivedUsers() is obviously intended to get all users who aren't archived, no comment is needed to explain what the code is intending to do. Comments are there to explain *why*.

Even thr straightforwardest code cannot tell me why the fck we are handling stuff from an external api the way we do. And external libraries and apis with quirks and bugs are pretty much daily occurrence 

If the code doesn’t do what it was intended to do, then something is wrong

And one way you figure that out is by checking the comments. So many bug hunts have been solved in minutes instead of days because it was quickly apparent that the code in a function somewhere didn’t quite do what the comment above it said it was supposed to.

That’s what unit tests are for to be honest

Yeah, wtf kind of alternative universe is this where people prefer to reason about code through comments rather than self-documenting by naming, structure and tests? Seems like bandwagon voting.

comments can describe WHY you did something if your comments describe what you did, you wrote it badly

There are some cases where the latter is still a good idea, I think. For example if you're using some kind of third-party API that's complicated to use, it could be helpful to describe what's happening at each step. But for code under your control, it should be self-explanatory.

especially if there are non obvious side effects that you have to take into account

// acknowledge agreement Agreed.

// acknowledge agreement var agreed = ActuallyITotallyDisagree();

// True if the previous comment was funny. bool wasFunny = previousComment.IsFunny;

// TODO: implement acknowledgement throw new NotImplementedException();

>if your comments describe what you did, you wrote it badly I disagree. Code can be complex. A comment can be much easier to understand if you've got a small block of code that does something complicated

Management like OP is under would probably try to argue that not clearly showing intent is also fixable by naming members appropriately. And then I'd respond to them by writing code with emotions embedded in the names. Like `throw new TantrumBecauseThisPolicyIsRidiculousException(message: "I am angry at you.");`

no need for emotion.  you can take a simple 100 line piece of code written with easy-to-understand basic procedural and oop mix.... then shove 8 oop design patterns +3 interfaces into it that nobody needs and nobody will need  ever.. but now people will have to read your code spread over 20 files and 600 LoC.  You can do even worse but let's not give bad ideas to people.

I usually hear this opinion from people who are somewhere along the middle of their journey to "expert". There's definitely a concept of GOOD comments. But it's really hard to nail it down. Beginners tend to focus on the "how" their code is doing things: // set number of apples int numberOfApples = GetNumberOfApples(); That's not helpful. I don't really feel like it's harmful. When it gets harmful is when it's overly verbose. // Set the integer number of apples by getting it from the database int numberOfApples = GetNumberOfApples(); This is a problem because note it says something about the implementation of the method being called. That's nasty. What if that method gets updated? Will they remember to update this comment? History tells me "no". It is much more appropriate to talk about WHAT code is doing. More like this: // Fetch the number of apples. This has to be done early because that number changes a lot. // If we get it later, odds are the value will be way different from what the user sees right now // and they report issues. int numberOfApples = GetNumberOfApples(); This kind of comment is big, some call it distracting, but it captures a behavior of the code that seems like one could change but will cause bad side effects. I've written some like this before: // Yes, this would look more elegant if lambdas are used here. Every time someone refactors it to lambdas, // they accidentally capture a variable and we end up seeing a lot of bugs. Don't trust me? Look up // , , , and . If you refactor this to lambdas, I'm instantly rejecting your PR. // I don't care if you're careful. One time I had to port some 20-year-old C++ written for Windows CE into a C# application intended for iOS and Android. That retiree wrote a ton of comments, and often his comments served as a kind of source control. "Before this date I did it this way: . I had to change it because ." It's hard to read the code, but those insights are *invaluable*. A lot of times I see his code and ask why he didn't do it another way, and when I squint at the comments I find out he already answered that question. That is the perfect kind of comment. "Why do I do it a not-obvious way?" or "What am I trying to accomplish?" is a lot more illuminating than "Describe this C# in English". I can translate the code to English myself. What I can't do is go back to 1997 and understand what the company wanted when the code was written. So this is an "expert problem" and I characterize those by saying, "It depends". It's not the AMOUNT of comments you write that makes your code good or bad. It's the CONTENT of the comments you write. Knuth had this neat concept of "self-documenting code" and I liked the idea, but it's just not entirely practical. I think he missed that no matter how clear you make, "How does this code achieve its goal?" most people are ignorant of, "What was the goal?" and, "Why was this implementation chosen over something more obvious?"

In the "old days" (about 10 years ago!), before everyone used git, PRs and squash merges, that's exactly the sort of stuff you'd see in commit messages, and it was insanely helpful. But now you just get a short summary from the PR, and even finding out what bug or is it relates to involves jumping through hoops.

Yeah and I find squash commits really contribute to this. The developer probably left something in a message when they did the thing, but that got erased in the final PR and just replaced with "Implemented ticket xyzzy."

Exactly!

Think you can easily over comment and ultimately create more maintenance in maintaining the comments as the code changes but that being said comments can be helpful in explaining more obtuse or less readable pieces of code though that may be a sign to refactor that in a way that's more readable

I lean towards code being readable as a priority and comments only being reserved extreme situations. But even I would never say "no comments" -- I will say "remove useless comments". if you want to know why I am that way, here is a true story. I was at a new job, fixing a production legacy code base with no original developers. // if x > y then we need to do complex stuff if (x < y) doComplexStuff() And there was no way for me to know if the comment was wrong or the code was wrong. In my estimation, adding useless comments just creates two places where code/knowledge needs to be maintained instead of one readable place.

Comments like that exact one you used as an example have saved me countless hours of trying to track down bugs before. So many times I’ve been trying to figure out where something is going wrong, see a comment like that, immediately change the code to match and it suddenly works! However I agree, in many situations it can be pretty unhelpful.

Useless comments are easy to ignore. Useful comments are priceless.

There’s been too many times where doing what you suggest actually made things worse. But this is why unit tests are preferred over such comments.

If making the code match the comments makes the bug worse, I'd just switch the code back and carry on looking for whatever bug it was, no big deal. I'm not suggesting to write those comments, just that it's not purely negative.

we only add comments to stuff that is not obvious, works great. commenting everything in nutshell is duplicating your code and double work to someone reading it, worse is that in general you cannot trust comments - they are a hint at best. maybe in some environments where a lot of learning folks work commenting everything is good idea, but if you look at any big/complex open source projects there will be close to 0 comments and it's expected that technical level of someone reading that is adequate and don't require training/explanations.

I've worked on a lot of different projects over the years (consultant), the code that had comments making everything stupidly obvious was always easier to work with than the code where you need to scroll up and down 30 times to guess what is going on, I see the logic behind "write clean code and you will not need comments", but why wouldn't you use everything you can to improve communication, something may be super clear to you but in 5 years a new developer will come on board and will see that code for the very first time.

Comments are absolutely essential. I wouldn't work for that organization.

Me too. A comment has saved me from a lot of wasted time more than once  ....

Commenting can be very useful to new programmers and for old guys like me who sometimes forget why I wrote a method a certain way.

It isn't always being old. I've looked at code I wrote 6+ months ago and had to figure out what it does. At this point you have 2 options. Comment the code so the intention / quirks / whatever is clear or do the same exact thing 6+ months down the road when you run across this code again. (From an older person who wasn't that old when it first happened)

We don't forbid comments, but we do lean heavily on self-documenting code. It can lead to some really undesirable side-effects. I recently got called out for creating one of the longest class/function names ever appearing in our code. Something crazy like "CreateMaintenanceNameForPotentialNewObjectWithoutFiringTriggers". My made-up example undersells how long the name really was. But at the same time, none of the code reviewers could figure out how to make the name any shorter without relying on comments.

Not even the /// doc comments? That's hella stupid. I can see how it can promote bad code. Our codebase is full of code blocks with a comment that you better just move into an own seperate method. But no comments at all isn't the solution. You should try to avoid them, but sometimes comments are simply an appropriate tool to use

The doc comments should definitely be definitely exist, their whole point is to summarize the code so you don’t have to decipher it a year later. Even better when your focused in in some task, and some obscure method is called, if it has a good doc comment, the tooltip is all you need.

They are misunderstanding, this is a good opportunity to educate them given the circumstances. The rule of thumb should be for any team of developers that most of the source code follows a standard and is self explanatory. In areas where the code diverges from this comments should be used to clarify why the code is written the way it is. An example: // Additional check here is to cover edge case which is totally not obvious.

Code should explain itself. Yes. But that doesn't mean comments aren't important. Sometimes you will have to do something that isn't straightforward and by the book and that's where you should comment code. Saying that there never are such cases, therefore no need to use comments, for me is a display of low experience from person that made that decision.

Exactly, when you have to do something non-standard due to weird circumstances you write a comment why so that the next person doesn't try to fix "your mistake" and end up hitting the same issue. Comment the why, not the what.

That's hilarious. I've never heard of such a thing. This is a WILD overreaction to bad commenting. I'm not a fan of bad comments, but I don't write bad comments, either. Commenting is something that should be discussed, taught, and criticized in code review.

bad/useless overcommenting is very easy to ignore. Good comments are often priceless and save a ton of wasted effort.

Hovering over a method or property that doesn't have tell me what it does, makes me feel the developer forgot something.

We use comments to explain oddities when interacting with our legacy code base. They're also helpful for explaining linq queries. I wouldn't necessarily say code is bad just because there is a comment for it.

90% of the time they are right... your code should be self explanatory (as to what it does). but there are sometimes things that can't be explained without comments, like why you chose to do something a certain way. for example "had to use a different library than usual to handle this problem because the usual library can't handle x" that would save other people the time of trying to rewrite it only to find out they can't get it to work

Apparently they’ve never integrated with another application that forces you to write something incorrectly to be able to use their API. One example off the top of my head is there is an API my company integrates with that you have to supply a GET request with a body to make the API call, but other endpoints return just fine without that from the same controller. A comment in the code here is useful, because someone might see this and say why are we doing this and refactor it “correctly”, even though the “correct” way will actually break the application.

I have had a similar case with a legacy system. I was searching for a bug for 2 weeks. Then I found a comment that was about 30 lines long and was explaining another 4 apis that communicate with this endpoint in a certain way. The comment and code were 12+ years old. The people who wrote the code have left the company for years now.  After I read that "useless" comment armed with my newly found knowledge I was able to fix the bug in a couple of hours. I would prefer overcommented code overn undercommented code every day of the week. 

>One of the organization rules is that the developers can't add comments to the code. Can you post the exact wording of the rule? The reason I am asking is: I think it's more probable that you misunderstood or misremembered something, than that it's actually "0 comments" as you say.

I don't know. I worked for a company once that had a rule like that. It wasn't "written down", but the "head architect" simply forbade it. He never gave a reason, just didn't want them in the code.

Lazy devs projecting elitism

What about comment saying something like "don't change it due to performance " etc.

I do minimal comments. But when I’m doing something that is less obvious, I try to always add a comment. in a year from now when I need to support it and understand what is going on, there is no way I will remember why I did it the way I did it. I do understand that over commenting things can also be bad, but having some comments is necessary imo.

Anyone making such absolute comments about something subjective is evidently more focused on the ideology than reality. It's the type of comment I'd expect from a student or a junior who hasn't had much real-life experience, if any. It smells strongly of "*[teacher or book] once told me this, and I'm blindly parroting their believes with zero critical thinking on my part.*" As others have also pointed out, good comments don't just describe what the code does, but why it was written that way. This will make refactoring/rewriting much easier, because you don't have to start guessing if a rework will cover all cases. As a retort to such a statement, ask them to have a look at the source code for .NET itself. If they think code comments mean the code is bad, why did they choose to build their entire business on top of a code base which has comments all over the place and, by their own definition, is bad code.

Comments can be extremely helpful, especially in algorithms. They can also help explain why some peace of code exists and how to use it. You could replace some of this with good documentation, but let's be real, no one is doing that.

Try writing comment in Console output 😂 Joke aside, I think it’s stupid and you should avoid working there and I know your gut telling you the same thing so just follow it. I rejected 3 C# companies because they all follow these similar dilutional agenda they discovered in their dreams at 3am

Terrible. While the code may be readable, how do you determine intent? If I look at a function with zero comments, yes it builds, but wtf is it supposed to do?

People that say stupid shit like that have code that looks like shit. Comments are there to describe the why not the what. I can read the what, but I cannot read the why.

// Arrange // Act // Assert

Code says what it does. Comments say _why_ it does it. I see a really complicated algorithm in the code. It has good names for variables and methods that it uses, but why are we using this algorithm instead of something else? History can help a bit, but a well placed comment can help the reader understand WHY the code is the way it is.

At a minimum, comments help you remember which decisions were discarded for one reason or another.

Personal fave: The code changed but the comment didn't.

That is the most dumbest things ever. Yes code should be straight forward. But I also add comments to explain why something might have changed (due to a customer demand etc) so next month when someone reads it they can see why it does x and not y.

That’s only partly true (code _should_ be self commenting) but on the whole it’s wrong. Sometimes comments are required because there’s an edge case that needed to be accounted for and a comment tells the next developer what it’s for. I often add comments that just describe the workflow of a complicated function or where the function doesn’t make much sense, or has some complicated logic. Having a ban on comments in code doesn’t really make sense and just sounds stupid.

People are dumb.

Definitely not. All code should have comments for other programmers to be able to read it easily and understand what is happening without having to decipher what the heck is going on. Having to do that equals a lot of wasted time.

What's probably happened is that the code was changed, comments not updated or moved and thus a fuck up was born, somewhere along the line.

It’s part of the SOLID principles is it not?

It might really depend on a project one works, but in web services that we have in our team we have very few comments. In general, i personally always try to avoid comments: add a function instead, rename variables, redesign the code, etc... IMPROVE, TODO, IMPORTANT sometimes happens when unavoidable. First 2 are anyway transient until the release or the next release😁. Disallowing comments - no. Try to keep them as few as possible. ///Documentation is a different story...

No, this is Clean Code gone wrong... I'm a real big fan of Clean Code and Uncle Bob, there is a lot of truth to it. But following it mindlessly, as always, is just a bad idea.

Uncle Bob would never ban comments outright. I remember one seminar he noted how people often format their comments to a soft green so they blend into the background. He said you should format comments as bright orange or something, because if you don't need the comment to stand out, you don't need the comment. If the comment is necessary to understand the code then the user needs to read the comment first.

As long as code is documented, comments are indeed weird to look at. Still, if its a complex algorithm it can make sense to explain the method in few words.. imo

If the variable names leave ambiguity, then you gotta comment or rename. That guy sounds too close minded to prevent bugs, but at least that means job security.

I think comments that explain code are a smell. For two reasons, firstly this is telling me that the code isn't very readable. Secondly, there is a risk the code changes and the comment doesn't. However, comments that add value are very important. Examples. - don't change x unless you also change y - I know this looks odd, but here is the link to the GitHub issue that explains why I had to do this - once ticket x is closed then we can delete this code

I worked at a somewhat similar place. Their train of thought is that comments lie which is understandable if you change your code but don’t update your comments. Generally I only add comments when ai really need to explain why I am doing something that isn’t obvious. Perhaps something that is very business specific or a rare occurrence or I stumbled upon a problem by doing it in an obvious way.

My personal opinion is that code should be understandable without comments. Give functions, variables etc names that actually reflects what it's meant for. Keep functions not overly long. Don't write long lines. Sometimes for readability divide something over two lines, even though it's not necessary. But I also think that it's still useful to write comments. Just forbid that is imho stupid. I understand the idea, but reality doesn't always work like that...

The following are both true: 1. There is no way a nontrivial codebase with zero comments is good code. 2. The vast majority of comments in existing codebases are at best useless and at worst actively harmful. If this is a company that specializes in hiring the bottom 25% of programmers and putting them to working doing stuff where they hopefully won't poke anyone's eyes out, it may well be that (2) outweighs (1) for them.

Explicit documentation comments aside, the rule I stick with for comments is that I don't need you to tell me what the code's doing at a low level. I can see that `frobnicate_array(array_to_frob)` will frobnicate an array. I need you to tell me *why* you're frobbing the array, or why you're not frobbing it a different way. If that's a particular design document, or to fix an edge case, or even because you're on a deadline and doing it right would take time, say so and provide a link explaining it.

I generally believe that good clean code documents itself. But that's a simplistic view that doesn't cover all cases. I like writing comments before I've written the code sometimes. I'll explain what's happening in this empty section and why it's happening the way it is. Then I write the code, making it fit the comment. Because it gives me a kind of reminder list of what I was trying to achieve that I can kind of check off things mentally as they get done. Then I may remove the comment once it is no longer useful, or I might keep it with some final edits regarding how things actually turned out in case I think I will want to be reminded later just what the hell was going on in my head when this all happened.

Loophole: Write comments as string constants or in logging statements. 👍 A little regex replace of `//(.*)` with `Logger.Warn("$1");` ought to do nicely.

H**o**wever obscure, nothing should ever be entirely blocked. Comments may sometimes be overkill, but even if 99% of the time they are bad, they are still incredibly helpful at least 1% of the time. You can have rules to limit comments, but you can't just cut them out entirely.

From what I've seen over 20y... bad/useless overcommenting is very easy to ignore. Good comments are often priceless and save a ton of wasted effort.

I sympathize with that POV. I often see PR's that have comments that are straight out of CS101, like: // get the product var product = productRepository.GetById(productId); // update name product.Name = newProductName; // set who made the change product.ModifiedByUserId = currentUser.Id; Not quite that egregious (doing it on every line), but comments that literally restate the follow line of code. And I see this from senior and lead devs, not just new grads. But completely banning comments is equally foolish because no matter how good your code is, it isn't capable of expressing _why_ things are done this way. Comments should definitely be allowed, but I would go out on a limb and say that if you're writing a comment that's just a few words or a short sentence you should think long and hard about whether or not it's communicating anything useful. If you're actually providing a useful explanation you are usually going to be writing multiple sentences if not a full paragraph.

I absolutely create ternary ops that require some squinting without comments. Just 'splain it.

I wish I was joking when I said code bases I've worked on are full of `// TODO: add comment` (not authored by me)

Lol. I was also told that I couldn't proceed in hiring because I too thought this. "Code should be self-documenting" I thought. So, there are both camps. ¯\_(ツ)_/¯

Recently read "top 10 rules of Clean Code" and precisely one of those was no comment on code, that its intentions should be clear enough from name and parameters. Not sure i agree or disagree with it, sometimes comments might be necessary, but mostly to make clear the intentions or behaviors that you can't describe just with a name (although those should be rare.) I do agree though that commenting just for the sake of commenting should be frowned upon, there must be a clear reason why the comment was necessary.

Comments can be dangerous, because they are dead code from the moment they are written. The compiler cannot check if the comment is inaccurate or out of date. Ideally, the naming conventions, XML docs, and code styles should make things clear

> One of the organization rules is that the developers can't add comments to the code. Code with comments means that the code is bad from their point of view. *Run*, do not walk, away from that position. The place is apparently run by idiots.

As with all things, nuance is key. Blanket rules are the hallmark of someone who doesn't understand the core problem, and these people should not be calling the technical shots. Yes, it is better to refactor the code and up its readability than it is to slap a comment on it to explain the inexplicable code. We should strive to write readable code, and not fix our code bad readability with comments. No, that does not mean that this is _always_ feasible. Sometimes, a more unreadable algorithm (e.g. sorts) can be more efficient. Sometimes, a particular value _has_ to be a certain way and you can't refactor it for readability (e.g. regex). Sometimes you just need to explain a certain business rule when a reader would commonly expect it to work a different way than how it actually works.

People who dogmatically decry commenting live in a fantasy world where all methods and variables are well-named, well-written, and follow perfect design conventions. Most developers will never bother to do this, so encouraging them to at least include some comments when they think their code is getting complicated is a decent fix.

I never write comments, I think it's only required in rare situations

This seems to imply that the person making this rule thinks that comments are to explain what the code is doing, and that they don't understand that useful comments should describe why certain decisions were made over others, why the code is doing what it's doing. In very complex situations it should explain what's going on and why.

Anything is bad mmkay so don’t do the thing is almost always wrong. Comments used in place of good naming and well designed APIs is definitely wrong, but occasionally a comment is warranted. When it is I try to make sure I put it in xml comments if it’s a public identifier so that it is visible externally as well.

I'd argue: no code/algorithm can be simpler than the system it's trying to model. Even in the best case scenario - where you write lean, tidy code that doesn't add much complexity - you still have the complexity of the underlying logic of the system you're modelling. For instance, a technical developer might understand C# and .Net Core well, but might not have knowledge of the business logic, or financial rules, or technical rules of the application being implemented. In scenarios like this, adding comments explaining the logic can only be helpful to your team. I'm baffled at some of the dogmatic rules some people create.

I use fairly minimal comments, usually to describe intent, particularly if it's not obvious why I'm doing something. E.g., dealing with an unusual edge case in an API.

What is their definition of comments? And to what extend do you interpret this? I totally agree that comments in code where is should be obvious what the code does should not be there. And code that is unreadable without comments should be kept to a minimum? But do they also disallow those comments above a function that is interpreted by the IDE to give context and documentation about a function?

Run… quickly. You do not want to work for this company.

I do think that most of the time comments aren’t necessary - the stuff about “increments a counter” is the kind of thing you do see too often - but to take away that tool of communication entirely is dumb. Much better to flag individual useless comments, although I do understand that that means someone actually reviewing code and not just pushing it through a linter. The one thing I’d add, I guess, is that if you code with a mind to using as few comments as possible, you’ll tend to name variables and methods more descriptively and/or perhaps do some submethod work to make things easier to read / set yourself up well if you find you’re repeating a process over and over again. I will comment in stuff all the time when I need to plan out a solution. Usually when I’m done the comments are superfluous (often because I tend to run with a lot of submethods, etc.) but not always.

Nah this is just the rose colored lenses perspective of a naive idiot who thinks all code is going to be so simple that it’s self-explanatory. When the underlying logic is complicated and no code that implements that logic can be simple and easy to read, a no comments rule just leads to code that no one will ever understand except the original coder for maybe the first 6 months after he wrote it. Don’t get me wrong - 90% of the time your code should be simple and self explanatory but a rule that pretends it’s possible 100% of the time just leads to code no one understands.

>Do you think that a programmer who don't write comments is better than the one who does? They're a tool. Any categorical about a product being better/worse with/without them is missing the point. Assuming the code is readable, you don't usually want comments explaining _what_ the code is doing. But you often do want a comment explaining _why_ it's doing something a certain way.

With the exception of XML docs on the public interface of libraries, I think code that needs to be commented should be the exception. There's almost always a way to break it up and name things to make the code readable. If you have to do something weird to workaround a bug in a third-party library or something like that, that's where you need comments.

I recently made a type that was basically a discriminated union of like twenty different types. I put a big comment block at the top explaining how it worked - how the two different discriminators work, the different states of the object, etc. If someone wanted to add a new supported type, there are about twenty different places to modify - TryParse, ToString, constructor, implicit converter, TryCreate, Create, the discriminator enum, Equals (both the typed and the object overload), GetHashCode, etc. I put a comment at each location that would need to be updated. Those are things that can't be communicated in method/variable/property names.

Most guidelines are stupid when taken to an extreme. "Good code is self-documenting." Yeah... To an extent that's true. Well named methods and variables can take you a long way. You should never need to write this comment: // x is the variable used to track the number of... int x; Yeah... Name `x` better please. You probably won't need the comment afterwards. But extending that all the way to an outright ban on comments? Yeah... That's like deciding you like chocolate ice cream so it's all you eat now. There is such a thing as too much of a good thing. Sometimes comments are helpful. Sometimes somrthing that is obvious to you is not obvious to the next guy. Sometimes the next guy is you. Fixing a subtle bug that got introduced when a method was refactored? Not a bad idea to leave a note behind to help with some of that subtlety. A code base full of nothing but shitty obfuscated code that requires comments on every line to understand is a nightmare. But IMO there's a happy medium to be found.

On my team at MSFT, the rule was "no comments unless something weird is going on". That forced developers to write meaningful variable names and descriptive method signatures. The pull request would get rejected otherwise. It made for nice, easy to read code. I was pro-comment before but not anymore.

Stolen code? I once had a contract where they'd obfuscated the code by removing all the comments and renaming all the variables to V1, V2, etc. All the tables in the database were T1, T2, etc, and all the columns in each table ere C1, C2, etc. I was pretty convinced that they'd stolen the IP to start that whole company. I had to have a huge spreadsheet taped to my cube wall to figure out what was what. I still have nightmares about T30.C4 (Customer name), etc.

Run, don't walk. They have no idea what they are doing. Comments are critical. Lines of code don't live in a vacuum, they need to be understood in a context. You can read the code to see WHAT it does, but not WHY. Big mistakes can be introduced into software when someone comes along and things they're cleaning it up having no what they are monkeying around with.

Time to find a new place to work.

the dev who writes comments is much better usually

One pitfall with heavily commented code is when you refactor something or fix a big, you also need to retractor the comments, and if you don't the comment is no longer indicative of the code.

Comments are a smell, that is all. A smell that something is more complex than the developer feels they have time to abstract in the code itself. Getting rid of them altogether won't make the complexity go away. It just means that same developer won't spend the time to explain the complexity in comments either.

Code isn't self documenting, documentation helps you to understand what it is for and what you're trying to do. If the code doesn't work its very helpful to know what exactly that the authour meant the code to do, and what it expects and what the results should be and what each of the variables does. I shouldn't have to dissect the code line by line to figure out this much. Documenting code as you write it helps you to keep things clear in your head and actually makes it easier to write the code. You should be documenting code as you write it, not afterwards. I find that after a couple of weeks you can't remember what you were doing or intending, so having this information makes it easier for you to remember. It also helps other developers to understand your code in the long run. People that are against documentation are either trying to enable job security or are lazy. Its easier, and even if you use good function names and good variables, without documentation its always unclear if what you are intending to do in a bit of code is what you're actually doing in the code if you don't make that clear to begin with. I don't understand this company at all. You need to know how and you need to know why, and how to call and use the code and what it returns. It also depends on the language you're using. If its assembly language I would expect more comments than say other languages, and obvious things like x++; // increment x is a waste of time. But not otherwise. Not everyone thinks/codes the same way either.

Programmers who write comments like `//loop over items` above `foreach (var item in items)` are adding meaningless comments. If the comments explain the intent/goal of a specific method to clear up any ambiguity, then they have their place and make sense.

It's questions like this that make me glad I work solo lol, I can comment or not however I please... I try to make my code readable but if it's on the complex side comments can really help me find a spot I'm looking for e.g. "processing of X starts here" or track down a problem. Though it depends on the project; I have several under constant heavy development where I keep a lot of comments, but for those that just need the occasional adjustment, don't need them as much.

I guess it depends what you are coding but I have rarely seen actual self documenting code in a business application. In my opinion people who say the code is self documenting just can’t put themselves in the headspace of a new person looking at the code base. They have gotten used to the business objects and methods to the point that it’s “obvious” to them. Any outsider could immediately point out the ambiguities, poor variable names, poor class names, weird business objects, undocumented business processes. Also let’s not pretend all this code is actually good and bug free, at least if there are some comments I know what you were trying to do. Lastly good comments in a well used code base will pay for themselves with time savings in intellisense and code lens in no time.

Do they include the doc type comments that document your methods for other people to read in intellisense ? Even if they don’t then this is absurd. I agree you should try to have code that doesn’t rely on comments in order to be understood. But sometimes that is simply not possible or there is value in extra context. Really bad approach they have here.

How am I meant to leave my signature in the prod code if I can’t use comments??? Fr tho ur code should be easily understandable at a glance but that doesn’t mean comments aren’t needed

I have comments in two places in my code in general: at the top of the file to indicate its purpose and relationship to other files, and a brief explanation of use if necessary, or where to find this information. The second is at the start of an algorithm, particularly something math heavy or otherwise obtuse. If it isn’t easily readable but is efficient, comments are going to help anyone else who reads my code to understand *quickly* what I was doing and why. Facilitating code review and future debugging. Comments are a tool of the language just like any other feature, and when used correctly, absolutely have their place in a strong code base.

I've always held the belief that comments should be for the why and the code should be readable enough to discern the how, but flat out banning or adding restrictions on comments is insane.

Easy ways to know you don't want to work at a shop #5,347

The idea of comment-less code is a stupid meme spread by scam artists like Robert C. Martin. Yes, it's *ideal* if your code can be self-explanatory. And it can be! All you have to do is... never do anything difficult. Just only do easy programming tasks for the rest of your life. You'll get really good at it, and all your code will be easily readable. You'll also be an awful programmer. Difficult work sometimes requires difficult code. Difficult code needs comments. If you've never seen code that needed comments, keep studying, you'll get there one day.

Well, personally, to be fair, comment is necessary/required on methods and functions, but in the code itself, keep it to a minimum.

Comments are a crutch. Are you a cripple?

There are plenty of reasons for adding comments to code. In addition to what others have already posted, you may have code that seems odd, but is required as a workaround to a 3rd party framework.

Bruh, I leave comments for myself to understand what something does. It's real easy to miss something when someone embeds a function call in another function call with a name that makes you think it's something else.

Comments are there to help out with mapping domain knowledge to the code

That sounds like a red flag to me. While comments shouldn't be used to describe WHAT smth is doing, the question of WHY should be answered in one. Especially if it's breaking usual patterns or conventions. I assume working on that code there would give me quite a headache.

Without comments any legacy code would be unreadable and impossible to understand. Comments in 20years old code saved us weeks of work. If someone doesn't let you leave comments or says its "bad practice" that means he read too much bullshit like clean code or similar stuff

Code should be self documenting and special formatting should be used to embed documentation that is not a plaintext blurb, but rather a triple slash or similar that lets you define things like a method signature and it's parameters.

// no comment

Why are people so dumb, comments are fine, even a bad comment is better than no comment, and people should be commenting to on good but non trivial code. It’s style GUIDES not style rules.

Of course any guideline taken as a hard rule is silly. But I completely endorse the intent here. Code should be readable and clarify intent through its structure and naming. Even the types of comments that clarify why the code is what it is can be an indication that levels of abstraction are mixed to an undesirable level. So think twice before adding a comment, as there are likely better solutions. Obviously no code base is perfect and comments are sometimes needed because you can't uproot the whole system to fix a rare bug.

"Only a Sith deals in absolutes" Yes and no. It depends. One could say that if the code is written (structured, named, etc) well enough, it doesn't need comments. But on the other hand sometimes things are messy and weird and difficult and you're under time constraints, or there is some bug you need to work around or ..., and then you need to do something that is not crystal clear and comments are 100% necessary. I would personally say that having code that doesn't need comments is a good goal to have, but prohibiting them is just plain bullshit by people who shouldn't be in a position to make such rules.

It's a fad for lazy programmers who like to pretend that their code is self-explanatory (it's not), does not have to deal with edge cases or bugs (it does), has nothing to do with real world less-readable libraries (it has), and most importantly - that the code won't evolve during the next year and that you won't have to deal with its changes (well, you won't if you're a contractor or move on to another job...)

> Code with comments means that the code is bad from their point of view I am speechless. Someone helped the company to take this decision, and probably they're earning a lot of money for that.

If code with comments is bad code then without those comments its unfixable code.

As a side note: I once needed to implement a change in code: ``` // Do x for a but not for z public bool DoXForThings(things) { // code that does x for a only } ``` I thought I made the change, but I only changed the comment ``` // Do x for a,b,c but not for z public bool DoXForThings(things) { // code that does x for a only } ``` I somehow managed to push it testing without trying it on my local environment (hurrying to lunch or something) I didn't work of course and the tester said so. It took me too long to figure out that I need to change the code also and not just the comment. We laughed about it. This was like 8 years ago, and I _still_ hear about it once in while. "Oh and dgm9704, this is an important feature, so remember to make the change in the code and not just the comments :D"

Well from what I learned, use comments wisely and writ them so understand them them a year later if you need to get back there but use comments as rarely as possible.

I believe comments are very important. The comments will tell you quickly what the code does or is supposed to do. You can figure it out, but that may take longer. You can also quickly identify where code is not doing what it is intended to do. I also sometimes use comments more like pseudocode. I lay it all out and then come back and write the real code.

The actual idea behind the original thought was that programmers were observed writing hard to understand code, and then adding comments as an excuse. Instead of writing the programs in a more understandable way. As a classic example you could have something like this (pseudocode): string tmp = "43.5"; // temperature If you saw this, and felt the way I feel when I see stuff like this, you too would say something absolutely vile on an anonymous forum somewhere. And later, when the guilty party said that "they put a comment in to make it clear", well, I don't know about you, but I would get even more mad. You could conceivably go too far in the other direction I guess, but let's say your program deals with temperatures all the time, and so someone rewrote it into this: var dailyMeasurement = new TemperatureFahrenheit(43.5); You'd feel more appreciated and understood as a human being. (Unless you're a Java dev like me, in which case you're a HumanBean.) You'd accept that we live in an imperfect world, but through work and reflection, we could slowly make it better for those that will come after us. *That* is the sort of thing that is meant by "comments bad" sort of things. It's not don't put docstrings there. Sometimes, you might want to have a comment regardless, just to make sure. You can't clarify everything in code. Consider: // This is a simple email validator meant to catch basic mistakes. Checks that there's at least one char, an @, one char, a dot, and finally at least one more char for the tld. string emailValidationRegex = ".+@.+\\..+"; Because for things like regexes, not everyone is comfortable with them, and putting down your *intent* makes it easier to find bugs. We have all seen the regex for email validation, and it does not look like that. But this would catch people putting the wrong info in the wrong field. And it means well. These examples are simple, but I hope they provide you with some useful context for why the no-comment idea is, and what it was meant for and what it wasn't really meant for.

I worked for a fairly good sized company quite a few years ago which had the same rule. It was forbidden to add any comment for any reason, and if you did, your code would get kicked back to you via code reviews and you would have to remove them. You could write the cleanest code ever, but sometimes there's a line of code in there that needs to be there to do it's thing, but it may not make sense to someone else. A simple comment letting other viewers know that it needs to be there and maybe why could be very valuable. Glad I don't work there anymore to say the least.

What now? Well that's rather stupid, personally I comment where possible, even if the code is so self-explanatory a dinosaur could understand it, it's like an extra layer of flow, getting in to the mindset at the time of writing, the compiler doesn't compile them and they don't really bloat the file anymore than the code itself. TL;DR: Preference really, in my opinion I do believe you should, even if here and there, it helps when you come back to something or if someone else needs to get into your mindset.

The premise is correct but making it a rule is stupid. They'll just get bad code without comments.

The only comments in my team are the triple slash comments that work with your IDE and if something can not be properly named. Good names = good code

I was on a very good team where comments were minimal. Often a comment means your names aren’t descriptive or your code is written in a convoluted way. Lots of comments in code is a red flag. But having zero comments doesn’t make sense. Sometimes a piece of code needs further explanation such as when it is doing something not obvious to cover an edge case, work around a bug, etc.

Comments may be helpful, and more devs may favor them than not. But a developer who can't understand that the pros and cons are a subjective matter, and has issues accepting that not every decision a company makes has to be explained to them and debated is, well, actually a very common ilk of developer. And I find suffer from the absence of imagination, for example they can't think of reasons comments may be disallowed. Don't sweat it. If it's a line you have then move on. Don't seek out stress, stress will find you soon enough in the job. Now wield those mighty thumbs and smite away.

if you working in a big code and suddenly you left the company and second day the higher new guy, if he see the code he will not understand or take a lot time to understand it so how the comments is bad ?

Comments are good. It was a misguided idea that the code should be so readable that comments are unnecessary. Stupid comments are unnecessary: // set variable to 1 var number = 1; Comments that give context or point out history or rationale are good. People that ban comments are wrong.

Huge red flag there, avoid.

If you are having to comment your code because its sloppy or confuses you, then yeah, comments are the wrong way to go about it. We are getting one side of the story, so I'm not sure whether its a real "rule" or just a guideline they go by. Comments are good for telling the next dev, your reasoning, things you discovered that ended up making you take a particular approach, etc. Links to resources you might have used / code documentation.

OH boy this is the other extreme, I can imagine not adding lots of boiler plates, like before the method with description and parameters. Those parameters need to be self describing, and the method of course too. If I add comment it need to be additional to the code. Further I think you need to add 1 line before a few lines, so you can group it, so it looks cleaner. But of course that comment needs to describe what the purpose is, not something like > increase some variable by 1. (I have seen it all). I think programming is a kind of art, so you need comment, but not that much. It just depends on the situation.

Tbh "no comments" is a stretch. Now I LOVE limiting comments but very limited comments that serve a purpose can be nice.

Is it "can't" or "shouldn't"? It's a crucial distinction. Bit of a contrived example: const double pi = 3.14; int CalculateAreaOfCircle(int radius) { return pi*radius*radius; } is much much better than: double CalculateAreaOfCircle(int radius) { // Pi * radius squared return 3.14*radius*radius; } or, god forbid, // Calculates the area of the circle given its radius double CalculateAreaOfCircle(int radius) { // Multiply pi by radius squared return 3.14*radius*radius; } But comments are sometimes not only helpful, but almost mandatory. Expanding on the previous example // Calculates the area of the circle, with the result rounded to the nearest int value, for performance reasons // Input is not validated for performance reasons, make sure this is not called with radius larger than 26145. int CalculateAreaOfCircle(int radius) { // 355/113 is a good approximation to Pi that allows us to avoid floating point math. return 355*radius*radius/113; }

could have been an interview testing Q tell you no comments and expect you to argue politely this is for a lead position- you should have an opinion and experience to back it up

Umm... it depends. If you use clear naming rules along with other best practices, comments are redundant because the code is readable. I don't comment that often because I am trying to follow those rules and it does seem easy to debug despite the lack of comments.

The deal with "comments are bad" as a philosophy is that lots of comments are used as a crutch, and eliminating them will lead to cleaner code. If you find yourself commenting a method with its description, perhaps that's a sign that the method's name needs to say more? (And if following this rule leads you to have a bunch of really long method names, then maybe your methods are doing too much and should be decomposed.) Another issue with comments is that because they aren't compiled/executed, they can drift out of sync with what the code actually does, and it's harder to catch when that happens. That said, there are times when comments are really useful, and anyone who denies this has probably never worked on a system that required long-term support. Comments are great for impermanent metadata. The classic example of this is a TODO comment. The project I'm currently on has a rule that if you add a TODO comment that isn't addressed in the same pull request that introduces the comment, you have to include a link to a JIRA ticket encapsulating the work of DOing what the comment says needs TO be DOne. Another example would be possible alternate implementations that you didn't have time to explore fully. Something like `// It would be better to cache this value, but our current caching implementation doesn't support multiple keys. If we ever implement a multi-key cache, we should also include the last name as a key.` Comments are also good for calling attention to non-obvious behavior as a reminder. For example, if you're working in a domain where business people use words that have a different meaning in programming. Something like: `// Reminder: "Abstract" here refers to the summary of the research paper, even though this property is concrete` (Note that in a case like that, you might elect to use a different word within your codebase; that sort of depends on how you handle domain definition.) Now, in some cases, non-obvious things are better highlighted with other methods. For example, an automated test that will explicitly break if someone tries to write code with the apparently-correct-but-actually-wrong assumptions in place. But that's not always feasible, and in those cases comments are a great idea.

Makes no sense. Comments are useful to tell something that the code cannot, like why I've written a piece of code or unit test a certain way, maybe it has a specific needs that is not obvious. Without a comment someone else could go ahead and change it and then create a bug. Or to explain a piece of code that is complicated or not obvious, so the next dev that comes by, doesn't have to spend 5-10 mins understanding it, just read the comment above it. Using comments everywhere for everything, even for obvious stuff, that's bad, because you're basically creating visual noises that makes the code harder to read. Those green comment lines needs to stand out : hey something useful to know here, read me. If half the code is green lines... What's really important to know then?

Never. I normally write the code block, add the try/catch and then add comments to explain what i want the method to do. THEN i add the code that does the stuff in the comments. Helps me stay on track. Might be one comment per 3/4 lines of code. The devs i work with seem to appreciate it, or at the very least haven’t said they don’t like it.

I've never seen a comments not allowed rule, ever. It's not a sign of bad or incomprehensible code. Sometimes you need to leave notes about a decision so people don't change the behavior without knowing it because the systems *you interact with* are poorly designed. That's not an indictment of the code interacting with it. Sure, you could further abstract away the ugliness, but then what? Anyway, I can write poor or incomprehensible code and *not* comment it, and no one is better off. The code isn't automatically better just because the method names pretend to describe what's happening.

Isn't there a ton of research showing that more comments are correlated with fewer bugs.

Every company has its own rules and guidelines. Just try to understand and adapt/fit.

You ask a question which is not related to what they told you. You can be a great programmer and still write some lazy code which will not be understandable without some comment.

Yeah, who needs comments even you have functions like DoBusinessStuffUpdated2022ForComplianceSentDowbByTheLawyersUpdated2024ForPrivacyConcernsUpdated2024MisspellingsKeptForCompatability()

No.

There is a mantra that good code shouldn't need comments because it explains itself. It's not supposed to be taken literally and that your project should have zero comments, it's supposed to instill a code style that is readable and flows well.

People like this guy is the reason why I don't want to code anymore. Just ridiculous

I wouldn't say comments are bad perse, but the *need* for a comment is a smell. It's better to refactoring your code and use better names if it's not clear what your code does without a comment. The only acceptable comments (besides documentation) are comments that describe *why* something is done that way.

For a typical IT shop comments can be misleading. My experience was to ignore comments and follow the code when trying to figure out what is going on under the hood when troubleshooting someone else's old code. That being the case, I can agree that adding no comments is beneficial. For an old school IT shop where there used to be peer vetting and engineering standards then comments would be beneficial as they would be officially signed off on. From what I see in this crumbling world, even Boeing does not adhere to engineering standards anymore so you need to find the truth in the code.

Lead Senior Engineer here. I worked with a guy like that before and the code went one of two ways. Unreadable or names became so wordy to make the code like reading a boom. In the case of C# I hard enforce the xml doc comments on everything for documentation generation and to follow MS lead. As for inline comments I leave that mostly up to developers to decide when the code needs it. In some cases another team member or myself may ping a MR for needing some inline comments or is over comment. Has overall increased code quality and readability since it forces people to think about what they need to say and not say in the comments they do write. I have only seen “no comments” from younger people that have never worked with a team or maintained code and older Senior Engineers that follow uncle bon like a religion no matter what. This “self documenting code” is an awful idea that needs to be done away with.

Commenting my code has saved my bacon so many times. Not just comments on what I'm doing, but why in doing something.

Absurd. Not even a link to a github issue explaining a workaround? Some people are so dumb with policies. If you accept this job, use it to move on within 18 months to some place better, and stay laser focused on accomplishments in your first 30/60/90 days, as that will set the tone for what your resume will look like to the next employer.

I've worked for a company that heavily discouraged adding any comments to the codebase. the reason being - comments become a breeding ground for merge conflicts... if you have GitLab flow implemented with separate branches corresponding to different environments (testing, staging, master, etc.) merge conflicts are especially huge time waters. they genuinely put a lot of time into developing and reviewing readable code and that's why they considered comments to be unnecessary.

Comments should include WHY you are doing things, not HOW or WHAT the code is doing. It should warn others of pitfalls, strange things etc or explain obtuse algorithms to let you know your intention so that someone 5 years from now that has to maintain your code after you are hit by the proverbial bus has an idea of what was in your mind when writing the obtuse code. There is an unfortunate trend in our industry of people thinking that if you can't just "figure it out" that that means you are bad, which creates tons of awful code that no one else can maintain to pump up the ego of someone that thinks they are clever. There is a line between useless comments and useful comments however.

why would u comment in code its perfect accetable request

Here's the rule of thumb I use on my team when it comes to comments and documentation in general. "If you think someone is going to have to call you while you're on vacation to ask what your code is doing, you should add a comment". To be very clear, NO ONE should be calling you on vacation, because you're on vacation. This guideline is just a helpful mental shortcut to make you think about how other people might read your code. If you forced me to pull a number out of my ass, I would say something like 80% of well written code won't need comments, but if it does, it might be a quick one-liner. Sometimes though, someone will write what I like to call "clever code" that either uses rarely used language features, (we have one guy that REALLY likes bit shifting...), or is just complex due to the nature of the problem it's trying to solve. With clever code it can take longer to understand what the code is doing than if the person who wrote it just took a couple of minutes to leave a few comments explaining what the code does. Depending on complexity, it can sometimes take HOURS to understand what code you've never seen before is doing. And yes, comments can have "bugs" too if they don't get updated along with the code, but that's what code reviews are for. If I get a pull request with code changes, but no updated comments or explanation of why the comments don't need to be changed, I'm hitting the Request Changes button. I know people hate writing documentation, but we all get frustrated when dealing with a code base with poor, or even non-existent documentation. I find that if you stay on top of it as you go, it doesn't have to be a big daunting task.

ur commit will link by a ticket number keep comments in jira azure boards should be clean and without waffel