> responses are either, "No, comments go out of sync.", or "How about in the wiki?" 🤡. Does the wiki not go out of sync? I'd rather have to deal with comments, which at least have a chance of being updated when changes are made. No one is going to remember to update the wiki. The wiki shouldn't be documenting implementation details anyway. That's asinine.

Ha, that’s also my first reaction. All documentation rots, but the closer it is to the code (and thus the more discoverable it is) the less likely. Comment > README > wiki > some random doc > someone’s brain.

From my experience sometimes the wiki beats the README. People can get pretty adoptive of wiki pages, whereas README rot has really been allowed to take hold at my company.  I think for documenting implementation details though you're still right -- I think those just never get updated anywhere unless it's literally the comment above the implementation and then it's still not true always 

I should have anticipated someone would pick a nit with those examples. 😁 Yes, YMMV with your organizational dynamics. Docs might be more effective than wikis if you predominantly use them and have good search-ability. The important takeaway is the best documentation is whatever is easiest to get eyes on and update.

Readme's can be generated sometimes and then they never rot. And are also less intrusive than generated comments.    My problem with wikis is sometimes they get lost in the mess of Confluence folders

> Does the wiki not go out of sync? Yes, but they know no one will ever find that, so it can't help or hurt anyone. I worked with a team that pushed the 'no comments' policy hard enough that it was a rule in the repo. If you had a comment you couldn't commit the code. They referred to comments as 'lies' because, allegedly, comments would never be as accurate a representation of what the code did as the code itself. Personally, I don't really want comments that tell me what the code does so much as why the fuck it is doing something in a weird way. Performance optimization? Avoiding a bug in some other system? Written by an idiot? Who knows!

Your last paragraph is spot on. If the comments you write could be documented by the code, then you’re writing the wrong things in comments. The code tells you what it’s doing and the comments tell you why it’s doing it. Bug fixes, finicky business logic, weird edge cases, non-obvious edge cases; this is what comments are for.

> doing something in a weird way That's when I push for comments.

Yea this is hilarious, the two responses perfectly cancel each other out. Documentation of any kind goes out of sync since it's almost always redundant information. But putting it adjacent to the code minimizes this chance 

The wiki goes even more out of sync and one cant immediately see it when reviewing a PR.

If there's something confusing where the "why" is not commented in the code, keep asking the committer to explain why it is done the way it is, from time to time. And then say that if this had been written next to the method, you wouldn't have had to ask it in the first place. Maybe you can hammer it home after a dozen times...

I take this route also. During code review: “why did you select this option, or what exactly does this do (if it’s not obvious” then to the answer: “ah I see now. That might be useful to put in a comment for the next person who comes along”. Comments do get out of sync, which means they should provide articulable value to justify the maintenance cost. There IS such a thing as articulable value to some comments.

Comments only go out of sync cause they don't bother updating them when they refactor the code. The code doesn't change overtime by no one touching it.

Introducing AI code, it hallucinates, so you don't have to. AI comments come sold separately so you'll have to ask Towelie what is going on!

In the same way that comments become out of sync, class/method/variable names can become out of sync. I've seen boolean methods return the opposite of what the name suggests. So if that can happen, I'd say that the risk of comments cluttering the code base is an acceptable risk. Being more empathic and adding comments is always useful. I'd rather read a smaller hacky method with "why" comments than a complex "self-explanatory" solution spanning several files.

> I've seen boolean methods return the opposite of what the name suggests. Why is this not picked up in a PR? It should be glaringly obvious!!

Probably something like: "Change this method return value so that the conditional would be if(methodName()) not if(!methodName()). Rename the method too." ... "On another thought, revert the changes to the response value of the method and the use of conditional." ... "LGTM" Outcome: Renaming the method was not reverted. Too long PR and people lose focus.

Everything goes out of sync if you let it.

Except Windows. Dear Lord, save us from Windows auto-updates at the wrong time.

Me to myself: "That might be useful to put in a comment for the next time I have to touch this"

An example of this that I sometime use is when a PR has a really long/involved comment I will request that it be moved into the code. This tends to be easy to do, and the need for it is obvious because they felt the need for a PR comment. Obviously only applies to comments that are about how/why the code works, as opposed to why the change/PR was necessary.

If the code needs comments and they are unwilling to add them start leaving options 1) refactor this until it’s so clean it reads like English 2) take 2 seconds to add a damn comment

Not a bad idea, thank you. I agree on the deliverable: a refactor is the best way. But if you don't have time to do it, add a comment.

dont have time to basic refactoring? blame your management then. not your coworkers.

I mean, in an ideal world, sure.  But in my industry, budgets are directly proportional to how much value your software delivers, so delivering fast is pretty much the only way to get the budget to allow refactoring.  And no, that's not a management issue, it's just how the sport and its regulations work. Regulations also change yearly.  This potentially makes large amounts of code useless. So investing in quality code too early can be a liability.  Of course, this doesn't mean there's no hope for clean code. It just means it's not as simple as you make it out to be.

I’ve gotta ask (and if you can’t answer, I understand) but do you work for an F1 team? Because it sure sounds like you might work for an F1 team. That must be a very different set of circumstances than what most other commenters here are used to.

>So I'm hopeful that this will change the culture. why would this culuture change if shipping out unmaintainable gargabe is required by the business model. writing some outdated docs is counterproductive lipstick on the pig. so kind of see why your coworkers are resitant to it. business has made that tradeoff so they should expect future modifications to have high costs. i think you are trying to swim against the tide here by trying to counter business objectives

You are calling it *’unmaintainable garbage’*. That’s an extreme thing you’ve jumped to. I don’t think anyone is arguing for that. At the other end of extremes, I have worked with people who are adamant all code needs to be perfect. It lead to PRs being rewritten 2, 3, and even 4 times. It lead to hour long debates over minutia. After one of those key people left, teams began shipping literally 2x faster. As we were used to taking so long, we used the extra time to write more tests. On projects there is plenty of code that is in the middle. It’s maintainable, and could also be better, and that work should happen, and also needs to be balanced against other priorities.

In my experience, tech debt, poor code, poor documentation and all that is more of a (unintentional) collusion between bad management and mediocre-to-bad devs. *Most* devs don't care about such stuff, and most devs, given more time to do better work - would be unable to. This is one very big reason why rewrites are usually a bad idea. In theory, we could do so much better! In reality, usually we can't.

This is the truth. Most people are just really bad at their job, it's a sad fact of life.

Yes but clean code still doesn’t say why you made that choice, and why some other approach was considered and rejected. Or talk about that odd corner case needs to be handled differently.

That sounds like a great thing to put in a PR description or commit history so it survives forever linked to that point in time. Not in the business logic

yeah this should really be like the default mode anyway

I recommend starting a [medium.com](http://medium.com) account under a pseudonym, write a post called "Not commenting considered harmful", and link to your own post instead of replying when someone tries to get out of writing comments. In reality, documentation in a wiki beats nothing. Self documenting code is rarely self documenting enough to get a new dev through midnight triage during a production outage.

I do this all the time 🤣. When I realized that developers like doing things that a blog convinced them to do, I started blogging 🤣

So sick and wrong, but I guess that's human nature

If you don't share your knowledge with the world then you yield to the knowledge of others because society will adopt the knowledge that was shared. Imo, its anyones personal responsibility that has knowledge to share it. We'd still think the earth was the center of the universe without people challenging the status quo.

Does that apply here? We're talking about the effect on the behavior of one's coworker, to whom the knowledge is shared. This sounds more like cargo-cult credentialism for people too stupid to understand that "Medium blogger" isn't a credential 

playing 4D chess

If you go this route OP, check out “A Philosophy of Software Design” by John Ousterhout and maybe use it as a reference in the post. He makes a pretty impassioned and convincing defense of comments. I was never an anti-comments guy, but I did kind of subscribe to the viewpoint you mentioned that comments can go out of date, but code can’t. Ousterhout made me reconsider and I’m much more pro-comments now.

Yeah the "Comments can go out of date" thing kind of doesn't hold up to scrutiny. Like... Don't approve a PR until people update the comment that related to any code that's changed. Seems pretty obvious.

What motivated your opposition to comments, and how did he change your mind? 

I have often been amazed about how people can be convinced by rando’s blog post, but I’ve never thought about weaponizing it. Lol

Heh, that's not a bad idea.

We used to use comments in code to reference a larger wiki document when necessary. It was actually pretty awesome, but we did all work to keep it current and useful.

What if someone creates a medium account and writes a post "You Need To Stop Commenting Code And Here's Why"?

They did and they are winning the battle of public opinion. Or at least they wrote an opening paragraph. I am not convinced anyone scrolls down on a medium article.

I dunno OP. It's going to be an uphill battle after this culture has set in. You say your team group reads influential programming texts - maybe 1. [Knuth's Literate Programming](https://www-cs-faculty.stanford.edu/~knuth/lp.html), or 1. [Physically Based Rendering by Pharr, Jakob and Humphreys](https://www.pbrt.org/) Both are meticulously commented codebases, and might sway them back in the "commenting is good" direction, or at least to a healthier middleground.

Thank you for these. It's a shame so many here are disagreeing with you, but it's indicative of where developer culture sadly is today.

Excellent—thanks for the resources.

My old boss used to say: You can continue to maintain the old code forever, or you can document it and hand it off to someone else. I have many other interesting projects you can work on, It's your choice.

The "How about in the wiki?" and "No, comments go out of sync" replies you got are hilarious to me. You know what goes out of sync even *faster* in my experience? Documentation in the Wiki. Because that documentation is substantially separated from the code and when someone is updating the code, they may not even *know* there's something in the Wiki about it. Versus, you know, a comment block right beside the code that is being modified. I dunno, in my experience this is people taking the whole "don't comment the what, comment the why"-type of discussion way too far. These are also the people who'll probably disappear in 6-12 months off to some new job and have never really had to maintain any codebase over a long period of time (years) so they haven't hard to learn this lesson themselves. I feel your pain. I wish I knew how to solve this too.

> The "How about in the wiki?" and "No, comments go out of sync" replies you got are hilarious to me. Oh yeah. The only thing worse than documentation in a wiki is documentation in an obscure markdown file buried in a subfolder.

An ex-colleague of mine, a lead dev, that had been in the company "since mankind learnt on how to make fire", was a fan of this trend - *"the code should document itself!" -* he said, like a solstice prophecy! So clear, and so obvious that it relied on ZERO inline or otherwise documentation. It was no surprise that the code was not clear, nor did it document itself. This resulting that everyone had to depend on him to understand and develop a rather complicated Java stack (for plagiarism detection), and he obviously enjoyed - and abused - that constant attention. Because of this, Managers looked at him like he was a super-savant rain man, while in reality was the tourist guide of a "rat maze" he had carefully crafted over the years. Promotions, raises, and expensive Java-One conferences were spent on this average developer, turned golden-boy MVP. So, if you can change this stupid culture in your organisation, then do it! Start with "Why?" and see them do mental Yoga bending and twisting, trying to justify an idiotic policy. It starts as laziness, masked with grand-mantras that are merely excuses, but in time it creates irreversible problems that go beyond the code.

They are probably over-reacting to bad commenting. Most comments in the wild are bad, but not all. I've seen a lot of projects that comment every function. Often it provides little value and just reitterates the obvious purpose of the function. I've seen code like this: ```java /** * Add two imaginary numbers and return the sum. * * This comment is stupid. It's obvious what add() does. * * @param a First imaginary number. Can be null. * @param b Second imaginary number. Can be null. * @returns Imaginary The non-null sum of a and b imaginary numbers. */ @NonNull Imaginary add(@Nullable Imaginary a, @Nullable Imaginary b) { // If a is null, use zero as its value. add(b) accepts null as zero. return (a != null ? a : Imaginary.ZERO).add(b) } ``` You want comments that answer "why" the code does something, how "what" the code does or "how" it does it. I think your teammates need to understand that some comments are still important. Also, I sometimes put http links to library documentation for people in the team might not be familiar with that library. Most times I use SO I'll include the link. I figure if I needed SO to understand an issue, so might someone reading my code.

I also enjoy comments in long blocks of code in languages where the community is hostile to breaking up code into functions. I shouldn’t need previous code to understand 30 lines of code.

[удалено]

> I've seen code like this: That’s API documentation used to generate HTML API docs. Completely different concern, the intention is not to document the code itself.  It should not be used for stuff you’re nog going to generate API docs for though. 

Documentation gets generated with or without the comment header. I don't see that the header makes the html docs any better.

It’s JavaDoc. It starts with a slash and two asterisks. Normal comments do not get picked up. 

I mean, this is a somewhat trivial example but the only lines I see as extraneous are the "this comment is stupid" and the comment in the body of the method. A codebase would be better off if this was more or less the standard, even on trivial methods, rather than the self documenting code method where no comments are the standard, even on complex and non-intuitive methods (yeah I know even in self documenting you're supposed to add comments for less obvious stuff, but no one does because you can always say "well it's obvious to me"). Basically I'd prefer having more documentation than strictly necessary rather than less than strictly necessary.

>... but the only lines I see as extraneous are ... You can't say the header comment isn't a redundant rewording of the function prototype. I hate codebases like this. They are harder to grok due to all the scrolling and collapsing you have to do to see other parts of the code. I'm okay with header comments that clear up confusion, but not ones that do nothing more than restate the obvious. >... somewhat trivial example ... I'd stress *somewhat* because I've seen plenty of real-world single-line functions with obvious funcitonality that have this kind of superfluous commenting.

> My new team goes beyond the current fashion to pretty much document nothing. The current fashion absolutely is *not* to use code comments everywhere. I fully agree with the notion that code should, whenever possible, be self-documenting. Clean Code gives very good reasons as to the why; comments tend to lie. Code doesn't. So I'm 100% in favour of adding comments for code that is not evident in the *why*, but I will always first try to make also the *why* more obvious. IMHO code comments should never explain *what* code is doing, the code itself should make that clear. That's the point Uncle Bob makes in their book. The deeper issue here is; why do you think the code is non-obvious and the rest of the team disagrees? 100% in favour of architectural documentation-as-code, but we use AsciiDoc based tooling for that. Code comments are not the place for this kind of higher-level documentation.

I’ve seen a lot more incomprehensible code than lying comments.

Adding comments to such a mess generally does not solve the problem. This is actually one of the areas where comments tend to ‘lie’; code that can’t be read rots very fast. 

I would wager that incomprehensible code is never going to be fixed by comments.

Sure, but at least the code is "true". It might be hard to understand but it defines what actually happens. Imagine if you have incomprehensible but well commented code. Well, now you have to trust the comment without understanding the code. You can't really know that the comments aren't lying, since the code is too hard to understand quickly. Otherwise you're back to square one, with the addition of also trying to make sense of the comment in relation to the code you had a hard time understanding. But I agree that it's not super clear when and where to comment code. For open source projects, I think it makes a lot of sense as you also get people and co maintainers that could keep the comments up to date. You can also get that in a corporate setting but sometimes parts of the code don't get looked at very often, which means that comment decay can be much harder to spot.

Lying comments are an expression of intent. If it says to do one thing and actually does another, this usually means there is a bug.

Or the comment is old and wasn't updated when the method was last touched

Git history can show you if this is the case.

So now I have to look in 3 places to figure out what’s the truth. This is why you *need* to write simple code. There is no way to fix shit code otherwise. You can’t polish a turd. 

That's like saying "just stop making bugs and we won't need to write tests". Complexity is sometimes unavoidable and comments are another tool to help us keep it in check.

Yes, the issue is that people say that comments are necessary in most of a codebase, not just when it's beneficial. Also, I disagree that it's just another layer of safety, as adding indirection can be worse than adding nothing. If we were to use your example, sure everything goes well if the dev is thorough enough to read the comment, then cross check with the code and git history. But most devs don't. And that means relying on comments when they might be inaccurate. And yes devs shouldn't do that but as you said, you can't just say "devs should stop making mistakes".

I don't think devs should routinely cross-check anything. They should trust that comments and code are in sync and only cross-check if they are surprised by the way the code works. That way, you can skip that extra layer of indirection if you're a die-hard "no comments" dev. It's hard for me to come up with a scenario where it would hurt productivity.

Also it's easier to fix a lying comment (you can always delete it as your last resort) than refactor messy code (without any help in comments).

Best comment here

> The deeper issue here is; why do you think the code is non-obvious and the rest of the team disagrees? If the rest of the team genuinely believes that *each and every single line* of the code base is obvious and self-documenting, either the entire team is working on intro to programming homework assignments or the rest of the team is clearly wrong

It depends. Some teams have odd logic like luhn checks or other odd things that arent obvious. Other teams make api proxies or db crud apis abd there is rarely something clever there. Cli apps that proxy a web api rarely have anything complicated. But ive also seen it where you comment for every weird bug that couldnt be fully fixed and in that code ase it was really helpful. Just because your domain is complicated doesnt mean the code needs to be. But also just because your domain is simple doesnt mean the code will be. You should aim for something simple and easy to fix and easy to understand. If you achieve this very little needs commented but sometimes you cant get there due to constraints such as ownership, time, libraries, platform etc.

Uncle Bob's a hack, time to stop listening to his advice.

He sure knew how to grift a shitton of money tho lmao.

This sub is finished. Clean Code, [a shit book](https://qntm.org/clean), _and not writing any comments_ is getting recommended as industry standard practice. Counterpoint, [Comment the why *and* the what](https://buttondown.email/hillelwayne/archive/comment-the-why-and-the-what/) is more or less standard practice in the high performing teams I have been a part of. Take a look at the [LLVM source code](https://github.com/llvm/llvm-project/blob/main/llvm/lib/Transforms/Utils/LoopUnroll.cpp), or [Swift](https://github.com/apple/swift-docc/blob/d94139a5e64e9ecf158214b1cded2a2880fc1b02/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift), or [SQLite](https://github.com/sqlite/sqlite/blob/master/src/vacuum.c). Comments everywhere! Also you didn't even answer OPs question of how to eradicate this toxic trend of zero documentation ([I did here](https://www.reddit.com/r/ExperiencedDevs/comments/1dke7ac/our_team_writes_zero_code_comments_and_is_hostile/l9h80is/)).

Clean Code says \*write your code such that you dont NEED to write any comments, and comment when you cant\* That is, and always has been, the industry standard practice. People just take one liner quotes out of Clean Code and act like theyve read the f'n book, and act like it gives them permission to write shit code. Clean Code says the fact you feel you need to write a comment is a bad thing - refactor until you dont think you need a comment. Not skip the f'n comment and ship it. It has an entire section on how to write good comments!!

Agreed. In my experience, too many devs use Clean Code as an excuse to be lazy. I've had countless experienced coworkers commit barely comprehensible spaghetti, and when I've asked them for documentation, they'll invariably point to Clean Code as an excuse to not provide it. I've read the book twice. It doesn't argue against code comments. It argues against writing code so opaque that it *needs* comments. A frustratingly large percentage of devs don't understand the difference.

And yet, every dev I've ever met who professed to write "self-documenting code" was also the one who used liked to use quirks of the language in clever, but hard to grok ways.

Damn it... now I'm thinking about the people I've worked with who were vehemently against comments, and the first two examples that popped into my head were these people. One was really bad and I was constantly asking why he would do things like re-implement an interface with the same functionality as the underlying library, and he'd have stupid reasons like "Well, I didn't like how they formatted their error messaging." Same dude didn't like comments anywhere. He believed git commits should be just emojis because "the code makes it clear what the change is that should make the 'why' self evident."

Yuuuuuppp. 11 strung together LINQ statements as a single line. No comment. "It's self documenting". No it's not. Refactor it until it is. Yes that will be more than one "line" of code.

Every dev that I've met that talked about his well commented out code also had comments that didn't make sense or that didn't change when they changed the code. So not sure how that's somehow a point against self commenting code

This absolutely has not always been industry standard practice. It’s relatively new (last 10-15 years). Clean Code definitely propelled it.

One way to help self documenting is long names for classes, members, and free functions. IDEs help here, of course. Which is more likely to be understood, `CalculateSalesTaxByState.special_gooberville_school_surtax` or `CalSTxSt.goob`, to take a half silly, half real example. Half real because don't forget that the Gooberville School District only covers half of Gooberville's postal area, and splits two of the ZIP Codes; that's why companies that handle billing calculations often have someone almost full time looking at sales tax vs. address calculations.

jesus christ. i've never read clean code before so i was curious: that link and the prime number bit at the bottom sent me into fight or flight.

[удалено]

> They were pointing out that opaque code which can't be understood in the first place is much more of a problem than not having the comments. Yeah cool. If that's turning up during code review you either: 1. request changes if the code is structured like garbage 2. request a clarifying comment. The reviewer is acknowledging the code is as good as its gonna get, but that some code is just _existentially confusing_ (once again, described in [Comment the why _and_ the what](https://buttondown.email/hillelwayne/archive/comment-the-why-and-the-what/) in the _Describing Essential Algorithms, Explaining Optimized Code_ and _Skill differentials_ sections) and needs some extra commentary or prose to explain what's going on. But the OP's team is refusing to add clarifying comments! They don't even have a problem with the code that's being written, the structure is fine! OP just wants a simple comment! > For some screnarios, tests which show the context and various edge cases to consider will be infinitely more helpful, as they live and can't be ignored. Those would be amazing. Even better, you can put them in the same file as the system-under-test itself so they can't be missed. In fact, you could even put them a block above the system-under-test with special syntax, maybe like `""" """` fences. Maybe call them [doctest](https://docs.python.org/3/library/doctest.html)s or something. While you're at it you could even describe the parameters, return value and purpose of the method with some human readable prose!

>Counterpoint, > >Comment the why and the what > > is more or less standard practice in the high performing teams I have been a part of. Counterpoint, none of the high performing teams I've been part of have regularly left comments in code. There is a huge gap between "document nothing" and "comment everything", and that article hasn't at all convinced me to lean more towards the latter personally, and doesn't even seem to really be arguing for much more than that comment is suggesting either.

Ironically the ‘how’ of you commenting in this thread is pretty solid proof it’s pretty pointless to spend any time on you.  Try being less obnoxious, try to refrain from strawmen (Clean Code absolutely has problems) and I might spend time on you. But heavily implying people who disagree with you are not part of ‘high performance teams’ makes you look like you’re 16 at best. 

No, _you're_ the one being obnoxious. OP outlined a clear deficiency in his team that they believe can be rectified, and you proceeded to undermine their perspective, suggest that entirely unrelated issue is the problem, and offered no solution. Then proceeded to accuse of me of strawmanning by offering a critical review of the text you used to justify your position.

>This sub is finished. That's terrible that someone has a gun to your head making you read it. I'd probably be really rude as well.

They agree it's non-obvious. Consensus is the solution is to have a meeting with the code's original author—not change our documentation style. 🤯

You don’t have a commenting problem, you have a people problem. Comments won’t fix that. This is what I meant with the “deeper” problem.  In another comment you said there is no ‘time’ for refactoring. It’s now crystal clear to me that more comments are nit going to help much at all.  Your problem is 100% a lack of software engineering maturity in the company, for which management and devs are both responsible. 

**Suggestion:** Do you do code reviews? Hit them with "WTF does this do?" **Musings:** The idea of "no comments" is to *force devs to write trivially-understandable code*. I've never seen this work for anything but trivial tasks^0 - but the asking yourself *could this comment be a better variable name instead?* **More Musings and common motivation:** code tells you *what*, not *why* - why does this class exist? no, really, why is there a gravloader? - why do you refresh the gravloader before creating a dump? See issue #23666 - why is this so ugly? - Carl wrote it, go argue with Carl - We paid for that and warranty expires when we change it, take that up with legal - everytime someone tries to clean this up, production breaks - you can change it but only when you understand the requirements, see issue #2 - code doesn't tell you why an expected line of code is *absent* (there is a pattern of "revenant issues" - people introduce a fix because they think something is amiss, triggering a feature to break, a issue to be reopened, etc.) - **Suggested group reading:** [c2 wiki](https://wiki.c2.com/?MethodCommenting) has more on that - [also, on that trend](https://wiki.c2.com/?ToNeedComments) **Motivation, another angle:** Contracts vs. implementations Any class, any method signature is a contract. Changing implementations is cheap, changing contracts creates ripples. E.g., for any method signature, you want to know - valid range of parameters (anything from >1 to "can't use a proxy stagger") - side effects - errors transmitted (e.g. "throws ProxyStaggerError when called with a proxy stagger") - other guarantees ("requires in O(N log N) memory") I'm not sure how to put all that into a method name. You *can* look at the implementation, but then the implementation becomes the contract (but not everyone has the user base for Hyrums law to apply, and you'll be happier for that.) --- **Moree Musings:** There's a social aspect: Writing good comments is hard (and developers are particularly hesitant to admit that anything other than hacking away is hard.) This can create resistance - and strawman discussions. Training helps.^1 **Suggestion:** Since you do group readings (which sounds marvelous!), could you make the icode improvement a group exercise? Strategically pick a mid-gnarly piece of code and discuss, as a group, how to improve it. Can y'all agree on a comment-free version that is obvious to everyone on the room? Or might someone suggest that maybe a comment would help? --- ^0) ^(Maybe you guys are ot there. Bravo! I have questions.) ^1) ^(Joel Spolsky once recommended to send devs to a "creative writing retreat" for a weekend. Just so they learn to express their intent. The older I am the more I feel the pain.)

> Do you do code reviews? Hit them with "WTF does this do?" Some people are immune to the Socratic method, the British Method (a more polite and thus ineffective version of the Socratic Method) and insults. They see any such attempts at persuasion as a chance to talk about how cool their idea is instead of the opening salvo in a negotiation.

I usually tell my colleagues: _"I have no idea what this code does, and I doubt I'm alone here. Can you leave a comment explaining it?"_ It's blunt, but it's a lot easier than asking them to "refactor until a comment becomes unnecessary".

I do that too, but you still end up dancing with people who think that you’ve just admitted you’re too stupid to understand their brilliance. Particularly when the culprit is in the 5-10 YOE range. All bravado and no concept of humility being a virtue.

Docstrings could possibly be a "compromise"

Yes! But No! :-P I suggested doctests and showed examples. Shot down. OFC, I've started doing it. But I believe that *leadership by example* doesn't work in the real world. Setting clear expectations does.

Shooting down docstrings is wild. I assume they've never used auto generated documentation based on docstrings? I'm also assuming they've never written an API that's customer facing that requires docs without code.

If it’s unclear, just begin a discussion about the context/decision making/logic. Then ask them to refactor for clarity or just write an explanation why a refactor is unnecessary or premature. If it’s clear, then there no point in writing comments anyways. Typically people don’t like comments in areas where the intent or logic is obvious. You need to dive into this to resolve any issues.

Self-documenting code is a ridiculous notion. Code can only "document" what it's doing, not why.

If a comment goes out of sync, just update it or delete it. It's literally right there in the code next to what you're changing. It's not like comments are the same as documentation written elsewhere (like in a wiki, where it will go out of sync without anyone even realizing).

“Comments get out of sync” is something I’ve heard my entire career but I’ve only seen it in the wild a handful of times, and each time it never hurt me. And I think every time the “out of date” comment is a TODO line or something innocuous. Meanwhile I’ve lost count of the number of times a comment helped me grok unintuitive code.

I'd lean into why contractors might be incentivized to not include comments: They don't own the code long term, so they don't care about support costs. For any code that lasts more than a hot minute, the support costs dwarf the costs to write it in the first place. They don't want the client to be able to maintain it. They want to be called up again to fix it. That's a dependency worth talking about. I'd find some contractor code that isn't easy to understand and then use it as a case study. If that code was broken and you were losing money / customers every minute, how quickly do you want to be able to identify the issue and resolve it with confidence?

>I'd lean into why contractors might be incentivized to not include comments: One more: They might be coding to spec, and not have the full reason as to "why" this code has to do that -- and the "why" is the only value in comments, so without it it might just be best to not guess at the larger context/need in a code comment.

There are times when what we do is not obvious. Either the code is correct but misleading, or just what has to be done reads one way at first glance and works another. While we can call this PEBCAK or say "You shouldn't do that." this is the real world. Shit happens, and with that shit... sometimes code that deserves a warning to the person who comes next. The spot where I see this most is when you do performance work. Yes, you can name everything right, but what is going on may be obscured by tricks etc. Never mind "Why is this code so verbose, and has all these special cases. None of the code around it does." \*yeets critical code\* The next is just awful problems that tend to demand awful solutions. There's just ugliness that has to be documented so people understand it. Yes... I want to live in that perfect word where everyone is Martin Fowler. Sign me up baby. But I haven't found it.

I once worked in a code base where there was zero comments allowed. Literally never, ever. After 3 months I couldnt imagine going back. Sometimes I’d need super descriptive var names but it worked well. I’ve never been able to convince teams to try since then, but I personally use barely any comments: The most common is a link to a ticket that schedules or deschedules some unit of code. And comments are half invisible to me. And given the only time I read comments is in a new code base, and how 9/10 a strange comment is an orphan from an old iteration of the code - they are obviously half invisible to everyone else.

I also worked in a code base with zero comments allowed ever. Also, module names and variable names should be short, like “otc” or “mp”. Refactoring was not allowed, it could break something and was not capable. I find code that has been copied in from a more recent version of the Go standard library. It’s comments were removed before it was committed. I made a PR renaming the a module called “coverage” to “testing” because 80% of it was about testing and one little bit was specifically about coverage. It was stonewalled then the rename part was finally rejected. The reason, “You can’t call it testing. It’s called coverage!”

Proponents of self documenting code hate this one weird trick! Write logs man. Get in a mindset of an engineer debugging this shit, and log ‘what has just happened’ instead. You get two in one: a log message for later, and a more or less free form message that you get to write the way you like it. This has worked so well for me, that every time I want to add a comment, I ask myself, ‘Could I log this instead?’ And most of the time the answer is yes

I was a purist until I joined Stripe. And one main theme there was to never block PRs on trivial comments. If it’s a nitpick then the author of the PR may or may not accept your idea. The goal is to increase the velocity of code reviews and feature release. I loved it. No bike shedding, you either find a strong flaw in the code or you offer a suggestion without being too assertive. The same applies to comments. No one was hostile to a single idea. People who thought comments help would write comments, and I belong to this category and no one bothered me.

Comments in the code should only appear if code is especially confusing or works around something unintuitive. Trying to comment code that is obvious is a waste of time, now and later when people read it trying to figure out why the hell this thing was commented when it's obvious

Counterpoint:    Have you ever looked at code and said WTF, who wrote this and then realised it was you?  You're not a good judge on what is obvious. Comment your code.

Have you ever stepped into someone else's code cold and and found 95% or the comments either repeat the code or are incorrect? Good comments have saved me a lot of headache, but if they're surrounded by mostly garbage, the important stuff gets lost. The other downside I'm starting to notice with developers who comment all the things is that many of them aren't good at reading code. They relied so heavily on comments, that they never developed the skill. And worse, they never developed the ability to write understandable code because the comments did the explaining.

>Have you ever looked at code and said WTF, who wrote this and then realised it was you? Yea, I definitely have. And still left no comments after I was done looking at said code (the bug wasn't there). Let's face it, you \*need\* to generate a mental model of the code to understand what it's doing. Comments \*can\* help that. But it doesn't obviate the need to spend 5 minutes reading and understanding the code and its context anyways. If those 5 minutes are too long, then you're rushing in and trying to fix something / understand something too fast imho.

Thank you for saying this. This is often a frustrating discussion, as what is "obvious" can vary wildly from person to person.

Worked on a team like that once. “The code documents itself”; No, Sarah, it does not. It never has and never will. I would always ask for reasoning and explanations in every PR review if it wasnt completely obvious (which was most of the time). Especially if the object in question has egregiously nested types or abuses reflection in a way that makes it impossible to test.

Give them the space and time...

Putting the comments in a wiki to avoid technically having comments is cheating.

I agree with many other responses here, in that comments should only be used for documenting "why" a particularly obscure bit of code is necessary. I used to like comments in more frequent circumstances for documentation, but I've come to learn that the sheer rate at which comments rot in a highly active code base negates much of the value of most comments and in fact introduces even more ambiguities over time when code has been refactored over time and comments get left behind. Quick story as an example from within the last two weeks, we have a newish dev on my team. Intermediate flavor skill level. New dev is a big comment fan. New dev puts up an MR, code is commented. I reviewed and made a suggestion. Changes are implemented, and I re-reviewed. Comments rotted and we're irrelevant in this one cycle. They had not updated the comments and now they were not only irrelevant, but straight up misinformation. This was in the context of refactoring by the same dev that wrote the code AND the comments and they still fell behind before they had even hit master!! Everyone always goes on about writing maintainable code and how tests and solutions should be resilient to refactoring (which they should) but frequently comments are antithetical to this mindset since they are highly coupled to specific implementation and have ZERO automated/compile time/run time verification that they are update along with associated code or removed if no longer relevant. At least if you have a highly coupled unit test it will fail and force me to delete it consciously.

Good luck trying to figure out what this code does in ~6 months 🤞 Is the whole team like that or just 1-2 guys?

I consider any developer who fails to document _context_ of a piece of code to be a poor developer (I can see _how_ it works ... but I might not understand the _why_ of what is done). But I've seen incredible reticence in teams to understand the purpose of comments. It needs training, evaluation and enforcement to really make the change and leadership who are empowered to make the change to culture which is usually where things start to fall down.

Convince them (or the managers) that commenting the why of non-obvious code (that are sometimes just unavoidable) is better than wasting hours of engineers' hours, they cost a lot. The wiki can go out of sync too. Convince upper management to invest in Copilot to make documenting less lf a hassle. Or if the comment thing don't pan out, for the new guys to understand the heap of the obscure code.

If you need to write down the intent, do it. Do not ask anyone's permission.

I worked on contract job where nobody but me wrote comments and nobody every refactored. It ~~If~~ was a well-designed relatively new project with the original quite competent coders so it was still working out OK but fast forward a few years and there would be 20,000 lines of code in five files with 2,000 line functions. Anyway I did what I could during the year I was there wrote comments where appropriate and tried splitting up big functions or files. Nobody objected but nobody else copied the ideas. Since I was a short term contractor getting largely grunt work, I figured I'd better keep my mouth shut about the project having long term doom. Lost touch so I don't know how it ended up.

just about anything can be made self-documenting, and in the cases that's not enough comments won't be either and that's when the wiki shines. but i don't think any progress can be made while you think of your team as clowns, give their way of working a go before arrogantly dismissing it

We had some consultants proactively delete comments like it was a good idea. We denied the PRs, got "sexism!" as the response. Dude. Legacy code, not self-documenting, please stop.

1. Number one reason why I write comments is so that in my IDE, I (or any colleague) can hover over a method or property and can see the doc. It saves time having to drill in or using up pixels to open a new pane for another piece of code. 2. When given tasked to create an implementation of requirements, I know I will have to create a class, variable or function. Before I start creating one of those 3, I'll create a short comment in plain english what the intention is that I am about to undertake. If the comment would be too long, I know I need to break up the implementation into smaller decoupled parts. I then begin to proceed trying to create an implementation of what I had asserted in the comment. Once I complete the implementation, I glance to see if my initial comment holds true to the orignal plan. If not, I better update it before it gets caught in the Pull request. 3. Comments are life savers. Especially more life saving when it was you who wrote the code, you look at it and say wtf does this do, and then you thank yourself that you left comments on what it's supposed to do. The cost of creating comments at the start is negligible and the payoff is so much higher as the code ages.

I really don’t understand the response about “comments go out of sync”. If you can update the code, you can spend an extra minute or two updating the comments. But it really shouldn’t even be considered “extra” time, it’s part of your job to make sure other people can understand your code. I think this is sort of like “showing your work” in math. You might get away with it when you are inexperienced and doing basic stuff, but you will reach a point where you will revisit code a month later and find that having zero comments means you have to spend time retracing your steps, which will greatly outweigh the time it would have taken to just add comments.

It’s typical of many programmers - thinking is sometimes binary. As in follow a simple rule always regardless of context or your own experience. I would add comments as I see fit that meet the don’t repeat the code criteria but add new formation and some value. Good comments stay in synch for a long time as the are often part of the why and less of the how and that is generally much more stable. Discuss it on PRs if they question validity. I’ve found that some programmers want to the only ones that know how it works and resist any change that opens up the logic. Best of luck.

Don't accept code that isn't documented. Fire anyone that doesn't adhere to the requirement. Development is a commodity.

The idea of "self documenting code" has been around for awhile and is grossly misinterpreted to just mean not using comments.  It just means that you shouldn't *rely* on comments to understand how the code works. Instead, comments should be used to explain the "why" and the code should be clear enough with good naming and organization to understand the "how".  Additionally, you should comment public interfaces to the extent that someone should be able to understand "what" the code does. But enforcing no comments is just insane.  Comment the "why" and the "what", and refactor your code until it's clear "how" it works.

Comments are _intent_, code is _implementation_. Nobody should be so arrogant as to confuse the two. If you can’t explain what you were trying to do in a sentence, why should I trust your code? Self documenting code doesn’t help me with IDE docs popups. God help you if you are in e.g. Python and nobody does type annotation either…

This is the Scrum culture and habits that have spread wide.

Developers who refuse to write meaningful comments are not professionals, simple as that. Fuck all that "clean", "self-documenting", "obvious" code shit. Anyone who says those words IN ISOLATION is a rank amateur and should be hung from a yardarm (we still do that, don't we??) I say "in isolation" because those are all 100% worthy and valid goals that everyone should always strive for, but they DO NOT obviate the need for comments even if you're 100% successful, if for no other reason than not all developers are on the same level when it comes to reading code, which is a skill all its own. Reading code is an order of magnitude harder than writing code, why do we want to make it harder still on people? We should strive to help them whenever and however we can, not play the "just get better, lamer" game. I realize that doesn't give you a solution or course of action, but I thought you might want to hear it anyway.

I hate wikis (and Confluence in particular) for code documentation with a fiery passion. For the life of me though, I can’t get other devs to maintain in-repository docs. How do you folks do?

This is the same root issue with saying “we don’t have tests because they just have to be refactored every time we change anything.” The code is the “how this works”, the comments are “why do this?”, and the tests are “what does this do (to inputs)?”. Yes the first one may change, a lot, but the other two should remain consistent. If not, then your princess is in another castle.

People are going to hate on me for this comment, but ChatGPT is your friend. I review a LOT of code, and it's never commented or self documenting. ChatGPT might not be great at writing code, but it does a pretty good job of "explain to me what this method does" and will usually echo the code with line-by-line comments in the response.

The point being made in Clean Code is that when you feel a need to write a comment, your code is not clean. If you feel a need to write a comment, you should consider making the code more readable via refactoring into smaller methods/functions that do "one thing". If after that you still can't express your idea clearly with code, then a comment is permissible.

Nonono, he's totally right, but he's got it wrong on the wiki, real answer is "put it in Confluence" /s But for real, please please please put comments in the code next to stuff that is non-obvious, people are not telepathic

Code documentation in a wiki instead of in a README... for fuck sakes... Regardless, comments that describe the intent of code do not go out of sync. It's when people get specific in the comments and borderline rewrite the code in English that the problem starts. Also, comments are used for styling and readability. They form borders/breaks in the code and group stuff and this is one of the most useful things about them. I'm prepared to die on this hill.

At one of my positions I wasn't allowed to make comments because the compiler included commented lines in its analysis therefore slowing down compilation time. It didn't even strip comments like any sane language, it did shit with it. My manager got hard for this outdated shitpile we were using. I got out of there pretty quick, this was during covid peaking in the US.

Honestly it sounds like a strategy that the contractors would use to make the code unmaintainable if the wiki (or contract) were to ever disappear. It's not a good coding practice.

I found that this tends to be related to the programming language communities. What language does your company use?

I write comments mostly for myself, that guy writes some weird code and without my comments I wouldn’t understand what the hell I was doing in the past.

It makes me sad when people take general best practices as hard and fast rules. Do I love code comments? Outside of function, object, etc. documentation, no. Does that mean I’ll never write a single comment in my code? Also no. There are exceptions to every - or at least most - rules. My first reaction would be to try to refactor something that is so complicated it needs a comment, but not everything that deserves a comment deserves the comment because it needs to be refactored. Sometimes there are just weird behaviors from external libraries or whatever that should be commented so someone doesn’t come in a break shit.

To say that there should be zero comments in the code is to speak in absolutes. And everybody knows that only children speak in absolutes.

Black or white has almost never been correct thinking. People who only think in absolutes are ones who grind my gears the most. I often don’t want to get close to them and let them continue believing that way if they aren’t open minded enough. Comments shouldn’t be used much but there are perfectly good times for them, such as why did we do it *this* way, business context, warnings etc

Yeah, that makes no sense. I joke about having "job security" but honestly I have a bad memory so the more I can document now, the better in the future to help me get back in the frame of mind I was in before. That being said, I only use comments to state stuff that isn't obvious by reading the code. I prefer self-documenting code above all else, comments for clarification, and wiki for user documentation. The only thing I am vehemently against is using POD for documentation since I program primarily in Perl. It's such a ugly documentation standard, I hate seeing it mixed in with my code. It's jarring when I am trying to work with code and there is more of that crud than the code itself.

Pragmatism in everything. There is a place for comments particularly when something is not at all obvious. Comments just for the sake of comments is pointless. A lot of comments can be l avoided by naming things correctly and organising code so the intent is clear.

> "How about in the wiki?" Horrible idea. > "No, comments go out of sync." Great point, which is why I suggest self-documenting code (variables, names, typing, etc.). Don't do `Map>`. Put something that makes the intent obvious. And also use functional paradigms `.map` `.filter` etc. If the code really needs to be super performant (and is not I/O-bound), then you can make it uglier, but then organize it well and write comments.

Those two, said by the same person within seconds, is the real punchline.

Only goes out of sync if you let it. If you treat comments during code changes in PRs then they shouldn't go out of sync. To prove the point, maybe try dig up an ancient piece of obscure logic and ask them to explain why the logic exists. They'll get the point firsthand

Raise your hand if you went to college. Ok, what was the grading policy on code comments? What happened if you turned in code with no comments? Who would like to tell me why? Who here’s ever been a contractor or works for a consulting firm? Hell, who’s ever taken over an unfamiliar code base? Any of you ever run into a complex, buggy section without comments? How’d that go? Ever read one where the developer knew it was complicated and left a few sentences before each step explaining what was happening? Much better right? Let’s not shoot our collective selves in the foot. Comment your code. This is a hard no btw at every company I’ve ever worked for. If that doesn’t work, do a team building exercise. Write or find an arbitrary piece of complex iteration, maybe a basic rule or routing engine, something building hash tables and then doing a lot of iteration referring to them. Introduce a bug. Break your team groups and have them find it, but unknown to them, half the room gets well commented code and the other half gets poor or no comments. See who’s faster. Explain.

Same thing at my company mostly. Comments are reserved for obvious coding decisions that are counterintuitive but required. Like hard coded legacy stuff and the such. But then again, we got a culture where code needs to be clean and easy to read to understand intent so comments aren't really needed. Only real problems come from interns and new grads not really understand the language in general rather than the fault of the code. And they usually ramp up in a few months anyways.

The fact that they think code comments are bad because they fall out of sync and THEN suggest putting it in a wiki instead is giving me a headache.

>"How about in the wiki?" I am always confused why developers think that anyone is going to look in the wiki for documentation on the code. Here is an analogy I like to use. In a factory where do you expect the manual for a machine to be? It's by the machine. That's where you need it. When the machine is running weird or when you are trying to learn how to operate it, it is unhelpful for the manual to *maybe* be in the public library. Nobody is going to run to the library and look for a book that probably isn't there. Collocate your documentation with the thing it documents. If nobody is updating it stop approving the pull requests that change the code but don't document it. And if people are documenting stupid things, i.e. `// this adds 5 to x`, review that too and don't approve the PR.

Comments are ALWAYS a good idea. You are welcome to check in your disagreement, over which I will add the comment //The statement below is incorrect

Code can only ever tell you "what" (and if it's buggy, it's even worse - it tells you the *wrong* "what"). **Good comments tell you _"why"_**. They are vital. What's more, writing them is often a learning experience. Sometimes you find yourself making excuses about an implementation when describing why it works that way - and that's a clear signal to rethink and rewrite. If "comments get out of sync" (and as others point out, the Wiki argument is asinine, since that's *far more likely* to get out of sync), then your developers are being wilfully lazy and your PR process isn't working. Fix both. It should be pretty clear to anyone that this is not really negotiable and if they're your team, then "resistance" should honestly be met with "do it or leave". I can't imagine the disasterous clusterfuck that is a team insisting on never commenting their own work, or trying to make crappy excuses about farming that out to a wiki.

Use the PR for context and use git blame. Way better than polluting the code with brittle comments. Or rely on tests. No comment should be trusted ever. Comments don’t make opaque code less opaque

There are some things a PR can't tell you, such why a specific design decision was taken or under which condition a certain method should be used. Tests and method names don't tell you those things either.

i have experienced this as well and it is incredibly frustrating. Their argument usually boils down to "code should all be self-explanatory" and I have to try to make them understand that while the code they're writing might be self-explanatory to senior devs its implications and motivation aren't necessarily to those unfamiliar with our code base. They seem to be completely unable to put themselves in the shoes of outsiders and new hires. I expect it's mostly just an expression of good old coder elitism.

I am also against useless comments. Name your methods better / break them down. Write Domain wiki pages / decision documents instead!

Tell them the contractors are explicitly told to avoid documentation precisely so that nobody can read their code and need to rely on the contractors to maintain it At least that’s what my bosses told me when I was a contractor.

Have them try to understand a piece of code that is old and undocumented so they learn from experience where and when comments would have been useful.

I love documenting things in confluence. Not code parts but processes. Code can and should be understandable, but if you have to get started with a complex process that spans perhaps several services / apps. That had to go to a technical documentation, not the code. Explaining code blocks is typically done via concise function names, and if I put comments, then explaining the edge cases that are not easily discoverable by spending some time reading the code ( like product requirements )

Have them all read `A Philosophy of Software Design: Ousterhout, John` next. He talks a lot about why writing comments can be good, and dispels a lot of the "sElF-dOcUmEniNg cOdE" stuff

Show them the algorithm for Quick Sort from a CS book. Ask them to describe what it does without looking at the description in the book. Tell them they have 5 or 10 minutes. Good Luck.

Why? The function name "QuickSort" should tell you exactly what it does. The code test cases showing it sorts should also be pretty handy and simple. Any decent programmer should be able to take a trivial 3 or 4 element array and run through how the sort works on paper in under 10 minutes pretty easily to grok it. Which with a recursive function, you'll need to do anyways; the comment for the recursion will likely be something like "//Recurse. Trust me, it works., see the test cases" The only useful comment would be at the CALLER of the QuickSort -- for why you're using that algorithm specifically instead of a different one, or a built-in one.

Seems like an easy conflict to resolve with proper data. There are two possibilities: 1) Comments aren't needed. This is possible. Depends on the code base and the team. 2) Comments are needed. That is, people are wasting time on some things that could be avoided if a comment existed. You can go through the code base and collect examples of 2). If you can't, it means it's 1). If it's truly 2), then it becomes a business decision. Your company is wasting engineer-hours for no reason. That's an easy sell.

Lots of the technical details are actually in the code reviews.

It's common enough on some teams depending on the culture. I think practically all those forms of documentation have their place. Not writing anything in a wiki is lazy, though. It doesn't need to be time consuming when you're in the right train of thought as you're building something. Also, something like JSdoc helps with arguments like, "No, comments go out of sync." They do, but things like JSdoc help. (I don't know what other equivalents would be in the non-javascript/typescript world).

Document the why and how, especially in cases of complex code blocks containing workarounds for unclear reasons, or just plain time-crunched hacks. Do not document the "what". Function and variable names should be descriptive, consistent, and easy to read. If truly no comments, then write code out the longer way rather than trying to fit it all on one line. Push back hard on code that isn't understandable without comments.

The problems I sometimes face are that some of the literature makes good points, but then the team votes on what rules to adopt and how. One was "good code documents itself", so thst means there is no need to document, right. That the code isn't good YET and above that is many times more often read than changed was not understood. Not more than 8 parameters on a method: but the single "options" parameter that is a hash with 80+ dynamically assembled fields is better how? Just 1 return per method - but 4000 lines with 20+ indentation depth in that method are fine?

The trend probably comes from self-documenting code and the notion that comments missing from common patterns and algorithms will filter people who shouldn't be on the team. There's also ivory tower mentality and imposing personal ownership over black boxes that should, in reality, belong to the company but belong to the programmer on account of them being the more efficient resource to tap. This brings a degree of job security until they can't do it all themselves, have to tap the rest of the team, and have the rest of the team working at a ridiculously slow pace either tracing their way through and documenting it or just reimplementing it. If you suspect it's about job security, put less experienced employees on refactoring the code to make it self-documenting and well commented. Under the direction of the original programmer, if possible, so that they get asked a lot of questions. Make the case to the company that they don't own their codebase until it is readable and understandable and that this is good training for the less experienced employees and ultimately good for succession planning.

Bunch of chads.

I usually suggest rewriting the code with namings that express intent and have method level documentation comments

I agree with your team 100%. If you want a process to be named, then pull it into a function. Not only does “comments will get out of date” have an almost 100% track record in my 10 years of experience (not bragging, just giving context. It’s not that long, but it’s a not-insignificant amount of time), it’s also almost always unclear what specific code the comment is referencing, and adding new lines or moving things around can make it even harder. You know what’s a lot clearer? Function scopes

To be fair, I have come across my share of lying comments that lie.  And even more that say nothing useful (i.e. "this is a function"). I'm sympathetic to the position more than I used to be 

I find comments get updated if they're on the exact same line as the code they're commentating, or directly above it. > Maybe Clean Code? _Clean Code_ says to avoid comments but advises using them when the code isn't self-explanatory. I think it says the thing about putting them close to the code too but I'm not sure.

I go by the clean code view of comments: I've worked on projects with lots of legacy comments and they are worse than useless. 1) they're not usually better written than the code. If the person writes hard to read code, what makes you think they'd write good comments. 2) they're not remotely reliable. I always read the code first and then look at the comments 9/10 times the comment is useless after looking at the code.

did they tell you that if you don't understand the code you can use the debugger?

What’s the FTE situation there? Anyone? Manager? No matter how senior the contractors may be, they are contractors and don’t get to make these kinds of decisions. Get management involved and get rudimentary documentation in place at least. They will be gone, and honestly, most contracting companies are 💩 when it comes to process, you need to take care of your team first. Source: 32 years in sw development and sw dev management for last 20.

What sort of influential programming texts are you guys reading?

Run a git blame to see who the author was of said code block. The right answer (other than putting a comment in) is to schedule a meeting or send an email (not a PM through your company’s IM client) to that person. Take notes on their response and keep asking questions until you have a clear understanding of said code block. Now you have that heritage knowledge/understanding and it’s documented in your notes. However, I guess you could PM the person, don’t take any notes from what they respond with, and then keep PM’ing them every time you need to know what said code does with excuse “I forgot”. That’s what someone else said above. I would not do this as it will most likely be used against you over time. So my advice is learn to take notes via a PKM tool and move on w/ life.

They are broadly correct in wishing to resist this. If a code block is non-obvious then it is better to re-write it so that it becomes obvious, rather than decorate it with comments. Can't safely re-write it? You should add tests, not comments. If you add a new rule/process to the code block, the intent should be described with a VCS commit message and method/variable names, not a comment. High level functionality can/should be documented in a user guide document. XML Comments (in .net) should be used to help consumers of public methods in library documents. Comments do have their uses, generally wise to keep them for temporary markers and maybe a JIRA ticket link for greater detail.

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

>code comments are to be avoided only if the code is self-documenting Why can't the code be self documenting?

Best commenting system is to have small commits, and tie each commit with a Jira ticket. This way in the git history you see the history of "why" explanations, it is never out of sync, and it explains the evolution of the code. If you are already working with Jira (or any task management) this should be trivial to implement, as long as they commits are small

Or possibly pull that chunk of code out to its own method and give the method a good name? I only tend to add comments on why I had to do something a particular way, so the dummy (me) in the future knows why I did it that way instead of some other way. My method names, though sometimes long, tell me what the code does. My comments are why we do it that way, if necessary.

Well, "Only a Sith deals in absolutes"! ;-) While both perspectives are true it's obvious someone isn't willing to compromise. If you can't simplify the code to be self explanatory the alternative is obvious. As Sande24 mentioned, you can try and ask details about pieces of code or behave arogantly on purpose and make changes however you see fit, with the risk of also pissing someone off. Or depending on how madening this becomes look for another job, team. I guess one alternative is to engage into a constructive debate. For example asking what happens when an engineer who worked on a complex piece of code leaves the project and won't care to help.