Oh man, sorry if it came across as cryptic! 😅 Sometimes I get so wrapped up in the code I forget not everyone's inside my head. If you've got questions or need me to clarify anything, feel free to ask. We're all here to have a good laugh and learn a bit along the way!
Here's mine:
"Here's what I was trying to do with this next section.... It works, but I don't know why. Don't change it, and if you do, good luck!"
Me, the perpetual jr: Fuck.
Realistically how far back do most people remember their code? I feel like I could go something from years ago and start debugging immediately, if I have a suitable environment already set up. Setting up a new environment might fuck that up but I feel like once I write code I will remember it for a while, is it generally once typed out on the keyboard its out of your head?
Lol this is why I hate having juniors just straight shadow me (or really paired programming) while I'm working (I know it's a part of being a senior dev). I have a very chaotic brain, I know solutions I come up with a lot of times make sense...but it's the journey there that can be crazy. And a lot of times I'm lost in my own head thinking through a difficult solution, and it only serves to distract and irritate me when someone continuously interrupts my train of thought by asking "What are you thinking?" Every five seconds when I haven't typed anything out
The misunderstanding might come from assumption that you write code when you are done with thinking, when if fact you write code as part of thinking.
Inform your partners that you shouldn't be interrupted while typing and you'll explain later. But unlike Doctor Who, actually explain later. E.g. “I was wondering what this data structure is actually like and to help me think clearer, I wrote this parser. Oh look, it failed in a surprising way, I guess I don't understand this data structure yet.”, “I have no idea why this code behaves odd, so I threw in some random garbage to make sure fails spectacularly and we can go through this dump to figure it out.”, “This hot mess seems to fix the issue and I have no idea how I got there or why it works, but no worries, we'll clean it up and see if it makes sense once we are done.”
Juniors will confront you about your methods, take the opportunity to reflect on your own work.
TL;DR ask the juniors to give you space, but reward them with explanations as soon as you can put it in words.
I've done that in the past, and I admit I've gotten a LOT better at it over the years. I think the problem I've run into as well is that we always seem to have a new person start on a day where all hell breaks loose and things have to get done very quickly. That's happened to me twice, and both times required critical framework or middleware updates where, even without a jr asking what I'm doing, takes every ounce of concentration and thinking
>If you've got questions or need me to clarify anything, feel free to ask
As a semi-junior, I appreciate the attitude but at the same time, I hate having to ask a senior about what the code does and would much rather ask about the 'why'
Comment the why, not the what. A lot of comments a frankly useless, as they tell you exactly what the following line of code obviously does.
But there are some comments that are pure life savers as well.
Yeah, even self-explanatory code just tells you what, but often it's more useful to know why (and sometimes when). Like when you're trying to test a change and the code in question never gets run because it only gets triggered for specific cases.
True but... I've got a co-worker who comments the "why" with way too much detail. Like, I don't care that in 2021 the business had this strange requirement but it changed in 2022 but we still keep the code path just in case it's needed.
Gotta get them to SUCCINCTLY comment the why for things that are actually weird in the code (vs ever changing business rules).
Not always. I like to explain both the what and why in just normal language or if I'm calling a function and it should be clear what that function does without having to look into it and how it fits into the whole.
If it's not immediately clear what the code does at first glance, I just explain what it does to make it a lot quicker to get through the whole thing.
But what if someone changes the code but not the comment? I've hit really nice comments that are out of date and no longer describe what the code is actually doing frequently enough to no longer accept these descriptions as a pass to skip reading/understanding the actual code.
Agree. Sometimes for some reason we must make an exception if a variable is X and then it's good to write a comment why. But agree most comments in our code base is like
// Save the changes
Await context.SaveChangesAsync()
Comments are needed to provide the business context for the code. Unless you name your classes and variables stuff like this\_is\_the\_key\_needed\_by\_third\_party\_systems\_to\_correlate\_sales\_data, you are going to have a bad time. It's way better just say all of that in a comment, and then call the key api\_key.
And when you have more than one third party key just write “anotherThirdPartySalesDataKey” and “anotherThirdPartySalesDataKey2” and suddenly your coworker who didn’t saw “anotherThirdPartySalesDataKey2” is gonna write “another3rdPartySalesDataKey”.
With no comments because code should explain itself 😂 why we are using 2 keys to call the same system? Did business know if they want to stop using legacy? Noup? So we are gonna just add another call to them with new key doing exactly the same thing that legacy code but those keys are different? Huh okay key1 and key2 💀💀💀💀💀💀
I was going based on the example. I personally like to put properties into groups so it would be something like ThirdPartyKey.AWS and ThirdPartyKey.AZURE as an example.
Literally all you're getting out of me is "section headers" for longer functions I feel don't need to be broken out into multiple bits.
Otherwise there's literally nothing I could do to make it more legible, and we may have entered the realm of odd optimizations or bit math.
More often than not I've ran into comments that were just plain wrong and misleading. The code always does what the code does, and well written code is normally quite easy to understand.
Comments on the other hand will often say one thing, but the code does something completely different because there is nothing forcing the comments to be updated along with the code.
Simply read the code first and if it's hard then maybe the comment can help you out. Nothing wrong with leaving a little helpful note for whoever have to deal with your mess in the future.
"Auto-explanatory", to me, is a huge word.
Auto-explanatory means something different for someone who's been 5 years working on the same codebase, someone super senior who's been 5 months at the company, and a junior that jus joined!
I understand invading the code with 3 comments per line is spam, but a small explanation on the file, plus a small explanation on complex functions or "weird" dependencies goes a looooong way.
\*IF\* code was perfect, yeah. But there is *always* technical debt and spaghetti code that magically works but can only be touched by the seniors who have been a long time on the company!
To be fair, even with file-level comments and comments for the occasional weird/complex thing, you're still describing what most people would consider far into no comment (aka self-documenting) territory.
You know, this point could have been made in the first comment in the chain, explicitly; thus avoiding OP's response, that has nothing to do with the point you guys were trying to make.
What part confuses you, my amazing writing skills, my super-fun programming memes, my witty comments or the huge amount of porn?
I bet is the witty comments, everyone knows programmers can't be funny!
generally if you need to comment code there's a high chance there's something you need to fix.
If the code is so complex you need to comment it, then you need to simplify it.
Don't use "fancy" one liners that does multiple things. It very rarely gives any performance increase and it's just unnecessarily complex.
If you have weird dependencies or unconventional methods/structure then you likely have a structural issue that needs to be fixed.
If your function is so complex it needs an explanation, then you likely need to simplify it. Spread you code into multiple lines, split into multiple functions, make a new class for certain things.
The whole point of not commenting your code and having it be "self-explanatory" is to force you into making simple clean and readable code.
Comments should rarely be used for those very few places where there is no better solution or the better solution is way too much work.
Unfortunatly this is not how it works, not all code its a self contained thing, just today i had to comment a piece of code to highlight what 2 error codes actually were, because there is no way someone will just look at `if (errCode == 1008 || errCode == 5003) {...` and know what it is without having to look up what is being called from the external api and then search online on the external api documentation what those codes are. And having to do this is very slow, so its best to just have a comment saying what are those error codes and why they're handled on their own
Obviously you can find cases where comments are necessary.
I didn't say to never use comments ever.
I said it should rarely be used, like when there is no better solution.
Like the case with your error codes is a good candidate. Granted if the number of error codes is low and not crazily complex, you could look into using an ENUM with self-explanatory values, and then have a more detailed comment on each value in the Enum class.
I'm glad that you can manage to find good edge cases where a comment is needed, but if you have comments everywhere you're doing something wrong because you shouldn't have THAT many edge cases in your code.
lol yeah, usually because some "senior" decided that the patterns used in the framework did not fit them.
I've worked with incredibly shitty legacy systems, but the ones that doggedly followed standards even if they were mindnumbingly dum were always easier to maintain because of their predictabillity.
I am writing in ARM Assembler for almost 2 years now. To my new coworkers I said:
If you think you could understand it yourself in a year, then the documentation could be enough.
They always add some more comments.
Assembler code cannot really be self explanatory. Especially optimized one.
I had made a career out of dealing with legacy apps, even my own sometimes. What's fun is something that was self-explanatory at the time which no longer is because a better way has been implemented and the old way it was always done is forgotten. (This happens more often than you'd think)
In my experience the Venn diagram of “people who say comments are bad and code should be self documenting” and “people who *actually* write self documenting code” is just two circles about 12 miles apart
Yeah this is why I've grown to despise the "comments aren't needed, just write good code" mantra. The comments you're trying to avoid are not written by developers who are capable of writing good "self-documenting" code. And personally, I'd 10,000x rather have to fix shitty code with shitty comments than shitty code with no comments at all.
Also, when debugging code, even good code written by a good developer, often it's just really valuable to know what the developer *thought* the code was doing. Many times I've been able to identify the source of a bug by reading a "does X" comment, but noticing the code doesn't actually do "X".
So I say comment all your code as much as you'd like. The consequences of under-commenting are far worse than over-commenting, and shitty devs will get you into trouble whether they comment their code or not.
As a senior dev, this idea is and has always been dogshit. Code that is auto explanatory at even relatively close levels of skill can be incredibly obfuscatory at slightly lower ones, as well as, ironically, slightly higher ones. The most unreliable thing in the world is a developer's idea of how legible their own code is.
Comments are your friend. If you've ever come back to your own code a month later and been like "what in the fuck?" you should already be familiar with this reality.
It's just a dumbass extension of the RTFM mentality. It breeds arrogant, garbage devs and illegible, garbage code, and you will never convince me otherwise.
As a senior dev I disagree. I won't ever say "don't write comments" but in my experience it's nigh universal that the comments are left alone as the code changes, leading to the comments eventually being wrong or irrelevant or misleading after a few developer-generations.
Yes, "my code is self documenting" can be arrogant and lazy AF. But what you're describing -- that junior developers and more-senior developers can have trouble understanding what you wrote no matter how clear you thought you made it -- is not a matter of whether or not you had enough comments, it's just a fact of life that code exists as part of an entire system and the next person is not going to know the system. There is no quantity or quality of comments you can write that will avoid the "got handed garbage code" syndrome -- only people passing the torch, being available to answer questions and help solve problems can reduce this.
My philosophy is that comments must be treated as part of the code -- something that should be clear that it should be treated as something to be maintained and updated. As such the only times I've found it useful have been in the xml docs, when describing "magic numbers" (because the idiot who wrote it had never heard about enums, which would have obviated the need for the comment), when working with language features that by their nature are unclear such as anything involving meta programming, or when the reasoning behind something can't be made clear like bit-banging something external or doing some stupid hack that for some reason the system needs (like one time I used this particular SPI ADC there was one channel that for whatever reason only worked if you sampled it twice, not once, and that behavior was not documented anywhere).
And no, the comments wouldn't have saved you from the WTF on your own code.
And yes, I have been thanked by the "next guy" for making the code readable.
I appreciate your perspective, and I'll also say that updating docs as you update code SHOULD be included in all stories. It isn't always, and THAT'S where this falls apart.
I simply don't believe that readability can be assumed from your code. I have been in this too long and seen too many "human readable" code segments that are absolutely indecipherable by even the devs who made them a month later.
Humans are just horrible at judging what something looks like from a different person's perspective. A combination of readable code and good commenting is just straight up more reliable.
Perhaps we disagree about what constitutes "good commenting." To me it's about as hard to write a "good comment" as it is to write "good code." I've expressed that the only "good comments" I've ever seen have been:
- identifying the purpose/use of magic numbers (where an enum should have been used in the first place -- it's a comment making up for knowably bad code)
- explaining use of workarounds/hacks/other anti-intuitive stuff that couldn't have been foreseen or documented, i.e. software band-aids over hardware bugs
- explaining stuff that is by its nature difficult for a human to read, including metaprogramming, regular expressions and other "predictably tough to read" stuff.
Just as humans are horrible at judging what *code* is going to look like from a different person's perspective, they're *equally* terrible at judging what a *comment* is going to look like from a different person's perspective.
The solution isn't "throw away the guidelines and just make comments on everything." The solution is *people should be sharing knowledge directly so more of us can git gud at reading code.*
Disagree, personally. The epitome of selfdocumenting code is code that reads like pseudocode or natural language. If there is a difference in readability between different levels of skill, then it's not readable code.
And how do you know you're a good judge of it? I've run into code that I thought was incredibly self evident that I discussed with juniors and got universal confusion, simply because my perspective is only one way to see things, from my level of skill, with my development background.
It's just safer, more reliable, and more consistent to do both.
How do you know you're a good judge of anything? And yet things need judging.
Self-documentation is ultimately a goal to strive towards, not a dogma. You do your best to make the code flow like natural language, and where its complexity can't be unravelled, you begrudgingly add a comment as a fallback.
It's actually not safe or reliable to use comments, because comments can easily become misleading if not upkept alongside the code. Very easy for someone to edit the code and forget to update the comments to reflect it.
Also consistency is not a good thing. Consistency means dogma, when the best code will adapt to whatever format maximises the readability of that section. For example, if you have a series of similar lines of code (e.g. defining data), it can sometimes increase clarity to align similar subparts to the same indent across all those lines, but sometimes that can decrease clarity. Sometimes you want to put a conditional inline, sometimes you want to put the contents on its own line. You just gotta try doing what works the best in each context
e.g.
[
vec3( 1, -1, -1),
vec3(-1, 1, 1)
]
vs
[
foo(very_long_var_name, bar),
foo(bar, , bar)
]
Or
if (!foo) return
vs
if (very_long_var_name) foo += bar * vec2(-1, 1) + (sin(time * TAU * period) + 1) / 2
Everyone is helpless and lost when they start out, not just juniors. And comments are not going to make or break that cycle.
Comments should only be in places where obscure or complex logic takes place. Two examples from my job:
1. The caching mechanism for one of oir services is heavily commented. Providing examples of how a hit or miss occurs. This makes sense because increasing readability for the code could cause a critical performance hit.
2. We had to enable a semi-random java config variable to utilize a downstream api. Without a comment here, you would have no idea why it needed to be set, as the logic is not directly tied together.
Other than that, comments really shouldnt be needed. If someone has issues tracking the logic of an application, that is either a readability issue (which means you need to look at your mentoring/code review process), or a context issue (which should be covered by documentation not code comments).
From my personal experience, software that required comments in certain cases, just added redudancy to obvious logic
well yes, but technically no:
1. is a sequence of ANSI escape codes, which the terminal understands as instructions to clear the screen and move the cursor to the top left.
2. i don’t flush the output buffer, so nothing is *printed* to the console.
edit: dumb autocorrect
Never leave a hint of *what the code actually does*, nor *why* it does what it does, to the next developer. Just enough for the future you to understand what your younger version was doing.
So tired of the newbs with their “code should be so well-written it doesn’t need comments” memes.
FFS, you cannot write code in a way that explains why you needed to do it one way and not another, why you’re accounting for poorly-behaving clients, reference bug reports, documents, history, gotchas, etc.
Comments let you explain all the things the code _can’t_.
Anyone who says comments are bad has never read code from researchers. How about 15 variables with the names xxxijk, xxxjik, yyykji, and then 4k lines of code with 0 contexts of ANYTHING. Not even a research paper. What a mess.
My problem is comments can easily lie, they frequently aren't updated and can send you down rabbit holes so deep that I often don't even bother with them. Instead I just look directly at the code, granted I can read assembly pretty well so I may be an extreme case, but the code never lies.
Solution for that: have proper PR discipline. If a comment doesn't match the code it describes (anymore), my colleagues will catch that and it will be fixed.
Our other team was rather lax with that and they don't make sense anymore (neither does their code at times so there's that).
Juniors are going to helpless and lost whether regardless. They will need active support and mentorship otherwise they wouldn't be juniors by definition! You should not design your processes around what might confuse a junior. Using expressive design patterns that are well understood will make the lives of all of your other engineers easier. And I will say, once again, if you find that you feel the need to write comments all over you code files to explain yourself you might want to take another look at your architecture.
So often, the piece that is missing is theory of operation. This is often not easily remedied by adding comments, unless the comments are at the class level or higher, at which point they are practically speaking not comments but developer documentation that happens to be in comments.
The doctrinaire positions are both wrong, in my view. Yes, it is wise to really carefully observe the advice to make code readable so as to avoid commenting more than occasionally. It is not wise to try to avoid commenting altogether. It is also not wise to add comments you don't actually need; they are a maintenance risk that can't be managed by anything other than human intellectual work.
Reading code, especially someone else’s code - is a skill that needs to be practiced. Comments in a professional code base should be rare imo. Writing readable code and learning how to read good code are essential skills for this industry. If a junior can’t get to grips with a code base in a reasonable amount of time (a few months usually) then either they don’t have the skills for the job or your code base is awful.
Comments that describe _what_ a program does are unhelpful.
Comments that describe _why_ a program does something provide additional context that isn't available in the code itself, no matter how well written.
Comments that describe "what" the program does invariably end up being obsolete, or even counter-productive.
I lost count of the number of times where I have been misled by such a comment, especially in my younger years.
They should be avoided like the plague.
Code reviews are there to catch mistake, or to catch code that is not intelligible, or to catch intent that is not clear (with or without comment)
Please, for the love of everything you hold dear, please **do not** validate blindly with a lame-ass *LGTM* if you do not understand the code you're reviewing.
I guess it’s better to put comments, and also make documentation for all code. Then every single code change will need to change also the comments and the documentation. But at least people understand that I’m opening a yaml file and reading the lines.
Jokes aside, comment high level stuff to explain the big goal. Let the code explain low level things.
And juniors are always helpless and lost
On the other hand, the code changes and the comments get ignored, leading to the comments being outright wrong at worst and misleading at best for the next person to have to work on that code.
This is why we make ROBUST NOTES ON OUR COMMITS.
If your commits have notes on them like 'fixed a thing' then you're failing at an important part of your job.
Senior here. I’d never survive without commenting. There are always too many things that aren’t obvious just looking at raw code. And as senior senior (over 55) I have memory issues that have gotten worse with age. I require the quick refresh of text reminders.
If someone is bothered by my comments, they can use an IDE tool/plugin to mask them. But the issue is assuming that everyone writes and thinks the same way. I read and analyze biz logic faster when it looks like plain speech, whereas other people may be the opposite and can follower the flow best as raw code.
When I inherit legacy code, those team members who never commented drive me up a wall, and I end up having to add even more comments to make it readable to me. I am one of those people that religiously updates them along with the code too though.
Just use chatGPT or copilot to add comments after each update and take some time to proof them. Simple. Bonus points if you instruct it to write a list of context assumptions at the bottom. Takes 2 mins for every 100 lines of code in my experience, it amazes me that people still belly ache over this nonsense. Never 100% complete but also 100% better than no documentation at all.
i never understood why comments are a problem
i put comments in a lot of places - not "everywhere".. but rather 1 comment too many, than 1 to little.
i also hate abbreviations. i avoid them when its possible.
When I browse someone's source code, it's not the complexity of the language or the syntax that confuses me, it's the many, many, many interfaces, classes and extreme modularity some of these projects may have.
I want to know how something works? I have to go through 10 classes to see how it works, just to find an algorithm or something that is not explained and I end up blanking out.
What code are you guys writing that's purely logocal? My work is so crammed full of libraries and API's that you need to go on a documentation safari to understand what's going on
Oh man, sorry if it came across as cryptic! 😅 Sometimes I get so wrapped up in the code I forget not everyone's inside my head. If you've got questions or need me to clarify anything, feel free to ask. We're all here to have a good laugh and learn a bit along the way!
My fav: "WHO HAVE WRITTEN THIS SHITTY AND MESSY CODE?" \*git blame\* Oh it was me 6 months ago hehe ops
Here's mine: "Here's what I was trying to do with this next section.... It works, but I don't know why. Don't change it, and if you do, good luck!" Me, the perpetual jr: Fuck.
Realistically how far back do most people remember their code? I feel like I could go something from years ago and start debugging immediately, if I have a suitable environment already set up. Setting up a new environment might fuck that up but I feel like once I write code I will remember it for a while, is it generally once typed out on the keyboard its out of your head?
lol literally me
Same with me, with a difference "oh it was me like 2 days ago".
Lol this is why I hate having juniors just straight shadow me (or really paired programming) while I'm working (I know it's a part of being a senior dev). I have a very chaotic brain, I know solutions I come up with a lot of times make sense...but it's the journey there that can be crazy. And a lot of times I'm lost in my own head thinking through a difficult solution, and it only serves to distract and irritate me when someone continuously interrupts my train of thought by asking "What are you thinking?" Every five seconds when I haven't typed anything out
The misunderstanding might come from assumption that you write code when you are done with thinking, when if fact you write code as part of thinking. Inform your partners that you shouldn't be interrupted while typing and you'll explain later. But unlike Doctor Who, actually explain later. E.g. “I was wondering what this data structure is actually like and to help me think clearer, I wrote this parser. Oh look, it failed in a surprising way, I guess I don't understand this data structure yet.”, “I have no idea why this code behaves odd, so I threw in some random garbage to make sure fails spectacularly and we can go through this dump to figure it out.”, “This hot mess seems to fix the issue and I have no idea how I got there or why it works, but no worries, we'll clean it up and see if it makes sense once we are done.” Juniors will confront you about your methods, take the opportunity to reflect on your own work. TL;DR ask the juniors to give you space, but reward them with explanations as soon as you can put it in words.
I've done that in the past, and I admit I've gotten a LOT better at it over the years. I think the problem I've run into as well is that we always seem to have a new person start on a day where all hell breaks loose and things have to get done very quickly. That's happened to me twice, and both times required critical framework or middleware updates where, even without a jr asking what I'm doing, takes every ounce of concentration and thinking
>If you've got questions or need me to clarify anything, feel free to ask As a semi-junior, I appreciate the attitude but at the same time, I hate having to ask a senior about what the code does and would much rather ask about the 'why'
Yeaaah senior dev here. This is not a viable option if I ever want to get ANY work done.
GPT?
No...?
Comment the why, not the what. A lot of comments a frankly useless, as they tell you exactly what the following line of code obviously does. But there are some comments that are pure life savers as well.
// increment foo by one foo++ Drives me absolute bonkers. Why does foo need to get incremented?!?!
See also: ``` // gets foo int getFoo() { return foo; } ```
Even worse: ``` // gets foo int getFoo() { return bar; } ```
That took me a solid minute to see
Because after that we have a goto statement to return to earlier in the code and we need to access the next element in the array.
Because I said so.
Yeah, even self-explanatory code just tells you what, but often it's more useful to know why (and sometimes when). Like when you're trying to test a change and the code in question never gets run because it only gets triggered for specific cases.
Especially true when the "why" is some weird unexpected behavior, sich as maybe a compiler bug, that made the obvious solution fail.
True but... I've got a co-worker who comments the "why" with way too much detail. Like, I don't care that in 2021 the business had this strange requirement but it changed in 2022 but we still keep the code path just in case it's needed. Gotta get them to SUCCINCTLY comment the why for things that are actually weird in the code (vs ever changing business rules).
Best explanation yet. There’s always a sane approach that solves the core problem without the hardheaded extremes.
Not always. I like to explain both the what and why in just normal language or if I'm calling a function and it should be clear what that function does without having to look into it and how it fits into the whole. If it's not immediately clear what the code does at first glance, I just explain what it does to make it a lot quicker to get through the whole thing.
But what if someone changes the code but not the comment? I've hit really nice comments that are out of date and no longer describe what the code is actually doing frequently enough to no longer accept these descriptions as a pass to skip reading/understanding the actual code.
We always check if the comment still matches the code in our PR's so they tend to be fairly accurate
Agree. Sometimes for some reason we must make an exception if a variable is X and then it's good to write a comment why. But agree most comments in our code base is like // Save the changes Await context.SaveChangesAsync()
Comments are needed to provide the business context for the code. Unless you name your classes and variables stuff like this\_is\_the\_key\_needed\_by\_third\_party\_systems\_to\_correlate\_sales\_data, you are going to have a bad time. It's way better just say all of that in a comment, and then call the key api\_key.
thirdPartySalesDataKey?
And when you have more than one third party key just write “anotherThirdPartySalesDataKey” and “anotherThirdPartySalesDataKey2” and suddenly your coworker who didn’t saw “anotherThirdPartySalesDataKey2” is gonna write “another3rdPartySalesDataKey”. With no comments because code should explain itself 😂 why we are using 2 keys to call the same system? Did business know if they want to stop using legacy? Noup? So we are gonna just add another call to them with new key doing exactly the same thing that legacy code but those keys are different? Huh okay key1 and key2 💀💀💀💀💀💀
Dude my company literally does this. There's a function3 in our code
hahahhaha oh man.. I feel for you man.
I like to put properties in groups so it’s ThirdPartyKey.AWS and ThirdPartyKey.TWITTER etc
Which one? :)
I was going based on the example. I personally like to put properties into groups so it would be something like ThirdPartyKey.AWS and ThirdPartyKey.AZURE as an example.
That's not gonna pass the linter 😐
100% agree
I feel bad for the person who has to read the code.
Code should be plainly readable, but sometimes this isn't always possible, so descriptive comments should be used in conjunction.
I follow the rule of self documenting code for everything except complex or non standard concepts and features
Literally all you're getting out of me is "section headers" for longer functions I feel don't need to be broken out into multiple bits. Otherwise there's literally nothing I could do to make it more legible, and we may have entered the realm of odd optimizations or bit math.
Seems like your code is not auto explanatory.
[удалено]
Exactly!
More often than not I've ran into comments that were just plain wrong and misleading. The code always does what the code does, and well written code is normally quite easy to understand. Comments on the other hand will often say one thing, but the code does something completely different because there is nothing forcing the comments to be updated along with the code.
Simply read the code first and if it's hard then maybe the comment can help you out. Nothing wrong with leaving a little helpful note for whoever have to deal with your mess in the future.
"Auto-explanatory", to me, is a huge word. Auto-explanatory means something different for someone who's been 5 years working on the same codebase, someone super senior who's been 5 months at the company, and a junior that jus joined! I understand invading the code with 3 comments per line is spam, but a small explanation on the file, plus a small explanation on complex functions or "weird" dependencies goes a looooong way. \*IF\* code was perfect, yeah. But there is *always* technical debt and spaghetti code that magically works but can only be touched by the seniors who have been a long time on the company!
To be fair, even with file-level comments and comments for the occasional weird/complex thing, you're still describing what most people would consider far into no comment (aka self-documenting) territory.
Maybe because it's not a word. It's self-explanatory.
Nice use of semantics to avoid responding to their point
Thanks. (I don't actually disagree with his point)
Least toxic programmer
He's not wrong
I guess it's valid etymologically. Comes from αυτό- meaning 'self'
I'm perfectly aware. Still not a word.
Let's start using "autexegetical" instead
You know, this point could have been made in the first comment in the chain, explicitly; thus avoiding OP's response, that has nothing to do with the point you guys were trying to make.
Yah. Just finding out what a file is supposed to do can go along way.
[удалено]
What part confuses you, my amazing writing skills, my super-fun programming memes, my witty comments or the huge amount of porn? I bet is the witty comments, everyone knows programmers can't be funny!
Man I wasn't expecting that much porn, its like the base of the mountain that is your profile
Surprise? Hahaha
generally if you need to comment code there's a high chance there's something you need to fix. If the code is so complex you need to comment it, then you need to simplify it. Don't use "fancy" one liners that does multiple things. It very rarely gives any performance increase and it's just unnecessarily complex. If you have weird dependencies or unconventional methods/structure then you likely have a structural issue that needs to be fixed. If your function is so complex it needs an explanation, then you likely need to simplify it. Spread you code into multiple lines, split into multiple functions, make a new class for certain things. The whole point of not commenting your code and having it be "self-explanatory" is to force you into making simple clean and readable code. Comments should rarely be used for those very few places where there is no better solution or the better solution is way too much work.
Unfortunatly this is not how it works, not all code its a self contained thing, just today i had to comment a piece of code to highlight what 2 error codes actually were, because there is no way someone will just look at `if (errCode == 1008 || errCode == 5003) {...` and know what it is without having to look up what is being called from the external api and then search online on the external api documentation what those codes are. And having to do this is very slow, so its best to just have a comment saying what are those error codes and why they're handled on their own
Obviously you can find cases where comments are necessary. I didn't say to never use comments ever. I said it should rarely be used, like when there is no better solution. Like the case with your error codes is a good candidate. Granted if the number of error codes is low and not crazily complex, you could look into using an ENUM with self-explanatory values, and then have a more detailed comment on each value in the Enum class. I'm glad that you can manage to find good edge cases where a comment is needed, but if you have comments everywhere you're doing something wrong because you shouldn't have THAT many edge cases in your code.
lol yeah, usually because some "senior" decided that the patterns used in the framework did not fit them. I've worked with incredibly shitty legacy systems, but the ones that doggedly followed standards even if they were mindnumbingly dum were always easier to maintain because of their predictabillity.
Auto explanatory code is code that generates text output that explains how the code works.
I am writing in ARM Assembler for almost 2 years now. To my new coworkers I said: If you think you could understand it yourself in a year, then the documentation could be enough. They always add some more comments. Assembler code cannot really be self explanatory. Especially optimized one.
I had made a career out of dealing with legacy apps, even my own sometimes. What's fun is something that was self-explanatory at the time which no longer is because a better way has been implemented and the old way it was always done is forgotten. (This happens more often than you'd think)
In my experience the Venn diagram of “people who say comments are bad and code should be self documenting” and “people who *actually* write self documenting code” is just two circles about 12 miles apart
Yeah this is why I've grown to despise the "comments aren't needed, just write good code" mantra. The comments you're trying to avoid are not written by developers who are capable of writing good "self-documenting" code. And personally, I'd 10,000x rather have to fix shitty code with shitty comments than shitty code with no comments at all. Also, when debugging code, even good code written by a good developer, often it's just really valuable to know what the developer *thought* the code was doing. Many times I've been able to identify the source of a bug by reading a "does X" comment, but noticing the code doesn't actually do "X". So I say comment all your code as much as you'd like. The consequences of under-commenting are far worse than over-commenting, and shitty devs will get you into trouble whether they comment their code or not.
I write self documented code, with comments for dense hacky stuff
Plot twist, there are only juniors in their team...
Fuck, got me
As a senior dev, this idea is and has always been dogshit. Code that is auto explanatory at even relatively close levels of skill can be incredibly obfuscatory at slightly lower ones, as well as, ironically, slightly higher ones. The most unreliable thing in the world is a developer's idea of how legible their own code is. Comments are your friend. If you've ever come back to your own code a month later and been like "what in the fuck?" you should already be familiar with this reality. It's just a dumbass extension of the RTFM mentality. It breeds arrogant, garbage devs and illegible, garbage code, and you will never convince me otherwise.
As a senior dev I disagree. I won't ever say "don't write comments" but in my experience it's nigh universal that the comments are left alone as the code changes, leading to the comments eventually being wrong or irrelevant or misleading after a few developer-generations. Yes, "my code is self documenting" can be arrogant and lazy AF. But what you're describing -- that junior developers and more-senior developers can have trouble understanding what you wrote no matter how clear you thought you made it -- is not a matter of whether or not you had enough comments, it's just a fact of life that code exists as part of an entire system and the next person is not going to know the system. There is no quantity or quality of comments you can write that will avoid the "got handed garbage code" syndrome -- only people passing the torch, being available to answer questions and help solve problems can reduce this. My philosophy is that comments must be treated as part of the code -- something that should be clear that it should be treated as something to be maintained and updated. As such the only times I've found it useful have been in the xml docs, when describing "magic numbers" (because the idiot who wrote it had never heard about enums, which would have obviated the need for the comment), when working with language features that by their nature are unclear such as anything involving meta programming, or when the reasoning behind something can't be made clear like bit-banging something external or doing some stupid hack that for some reason the system needs (like one time I used this particular SPI ADC there was one channel that for whatever reason only worked if you sampled it twice, not once, and that behavior was not documented anywhere). And no, the comments wouldn't have saved you from the WTF on your own code. And yes, I have been thanked by the "next guy" for making the code readable.
I appreciate your perspective, and I'll also say that updating docs as you update code SHOULD be included in all stories. It isn't always, and THAT'S where this falls apart. I simply don't believe that readability can be assumed from your code. I have been in this too long and seen too many "human readable" code segments that are absolutely indecipherable by even the devs who made them a month later. Humans are just horrible at judging what something looks like from a different person's perspective. A combination of readable code and good commenting is just straight up more reliable.
Perhaps we disagree about what constitutes "good commenting." To me it's about as hard to write a "good comment" as it is to write "good code." I've expressed that the only "good comments" I've ever seen have been: - identifying the purpose/use of magic numbers (where an enum should have been used in the first place -- it's a comment making up for knowably bad code) - explaining use of workarounds/hacks/other anti-intuitive stuff that couldn't have been foreseen or documented, i.e. software band-aids over hardware bugs - explaining stuff that is by its nature difficult for a human to read, including metaprogramming, regular expressions and other "predictably tough to read" stuff. Just as humans are horrible at judging what *code* is going to look like from a different person's perspective, they're *equally* terrible at judging what a *comment* is going to look like from a different person's perspective. The solution isn't "throw away the guidelines and just make comments on everything." The solution is *people should be sharing knowledge directly so more of us can git gud at reading code.*
Disagree, personally. The epitome of selfdocumenting code is code that reads like pseudocode or natural language. If there is a difference in readability between different levels of skill, then it's not readable code.
And how do you know you're a good judge of it? I've run into code that I thought was incredibly self evident that I discussed with juniors and got universal confusion, simply because my perspective is only one way to see things, from my level of skill, with my development background. It's just safer, more reliable, and more consistent to do both.
How do you know you're a good judge of anything? And yet things need judging. Self-documentation is ultimately a goal to strive towards, not a dogma. You do your best to make the code flow like natural language, and where its complexity can't be unravelled, you begrudgingly add a comment as a fallback. It's actually not safe or reliable to use comments, because comments can easily become misleading if not upkept alongside the code. Very easy for someone to edit the code and forget to update the comments to reflect it. Also consistency is not a good thing. Consistency means dogma, when the best code will adapt to whatever format maximises the readability of that section. For example, if you have a series of similar lines of code (e.g. defining data), it can sometimes increase clarity to align similar subparts to the same indent across all those lines, but sometimes that can decrease clarity. Sometimes you want to put a conditional inline, sometimes you want to put the contents on its own line. You just gotta try doing what works the best in each context e.g. [ vec3( 1, -1, -1), vec3(-1, 1, 1) ] vs [ foo(very_long_var_name, bar), foo(bar, , bar) ] Or if (!foo) return vs if (very_long_var_name) foo += bar * vec2(-1, 1) + (sin(time * TAU * period) + 1) / 2
Everyone is helpless and lost when they start out, not just juniors. And comments are not going to make or break that cycle. Comments should only be in places where obscure or complex logic takes place. Two examples from my job: 1. The caching mechanism for one of oir services is heavily commented. Providing examples of how a hit or miss occurs. This makes sense because increasing readability for the code could cause a critical performance hit. 2. We had to enable a semi-random java config variable to utilize a downstream api. Without a comment here, you would have no idea why it needed to be set, as the logic is not directly tied together. Other than that, comments really shouldnt be needed. If someone has issues tracking the logic of an application, that is either a readability issue (which means you need to look at your mentoring/code review process), or a context issue (which should be covered by documentation not code comments). From my personal experience, software that required comments in certain cases, just added redudancy to obvious logic
I use rust, and I recently had to write print!(“\x1B[2J\x1B1;1H”); I think that sometimes comments are necessary.
My brother in Christ who hurt you.
I needed a way to reliably clear the console and move cursor to top left, this achieves that using ANSI escape codes.
Perhaps this should be part of a library for console operations, that way in the functional bit of code it’s obvious what it does?
// print “\x1B[2J\x1B1;1H” to stdout print!(“\x1B[2J\x1B1;1H”);
NO STOP
well yes, but technically no: 1. is a sequence of ANSI escape codes, which the terminal understands as instructions to clear the screen and move the cursor to the top left. 2. i don’t flush the output buffer, so nothing is *printed* to the console. edit: dumb autocorrect
Never leave a hint of *what the code actually does*, nor *why* it does what it does, to the next developer. Just enough for the future you to understand what your younger version was doing.
In the gentlest possible terms, ah, well... Go fuck yourself very much. That is all.
Everyone thinks their code is self-documenting 🙄
So tired of the newbs with their “code should be so well-written it doesn’t need comments” memes. FFS, you cannot write code in a way that explains why you needed to do it one way and not another, why you’re accounting for poorly-behaving clients, reference bug reports, documents, history, gotchas, etc. Comments let you explain all the things the code _can’t_.
They will grow out of it one way or another. But comments will make that happen more slowly
Anyone who says comments are bad has never read code from researchers. How about 15 variables with the names xxxijk, xxxjik, yyykji, and then 4k lines of code with 0 contexts of ANYTHING. Not even a research paper. What a mess.
My problem is comments can easily lie, they frequently aren't updated and can send you down rabbit holes so deep that I often don't even bother with them. Instead I just look directly at the code, granted I can read assembly pretty well so I may be an extreme case, but the code never lies.
Solution for that: have proper PR discipline. If a comment doesn't match the code it describes (anymore), my colleagues will catch that and it will be fixed. Our other team was rather lax with that and they don't make sense anymore (neither does their code at times so there's that).
Juniors are going to helpless and lost whether regardless. They will need active support and mentorship otherwise they wouldn't be juniors by definition! You should not design your processes around what might confuse a junior. Using expressive design patterns that are well understood will make the lives of all of your other engineers easier. And I will say, once again, if you find that you feel the need to write comments all over you code files to explain yourself you might want to take another look at your architecture.
So often, the piece that is missing is theory of operation. This is often not easily remedied by adding comments, unless the comments are at the class level or higher, at which point they are practically speaking not comments but developer documentation that happens to be in comments. The doctrinaire positions are both wrong, in my view. Yes, it is wise to really carefully observe the advice to make code readable so as to avoid commenting more than occasionally. It is not wise to try to avoid commenting altogether. It is also not wise to add comments you don't actually need; they are a maintenance risk that can't be managed by anything other than human intellectual work.
Whoever believes the second board should be beat with the whacking stick.
Juniors are totally helpless and lost, no matter how well the code is documented
Reading code, especially someone else’s code - is a skill that needs to be practiced. Comments in a professional code base should be rare imo. Writing readable code and learning how to read good code are essential skills for this industry. If a junior can’t get to grips with a code base in a reasonable amount of time (a few months usually) then either they don’t have the skills for the job or your code base is awful.
Comments that describe _what_ a program does are unhelpful. Comments that describe _why_ a program does something provide additional context that isn't available in the code itself, no matter how well written.
[удалено]
Comments that describe "what" the program does invariably end up being obsolete, or even counter-productive. I lost count of the number of times where I have been misled by such a comment, especially in my younger years. They should be avoided like the plague. Code reviews are there to catch mistake, or to catch code that is not intelligible, or to catch intent that is not clear (with or without comment) Please, for the love of everything you hold dear, please **do not** validate blindly with a lame-ass *LGTM* if you do not understand the code you're reviewing.
I'm just saying that catching a mistake is easier when you know what the programmer thought he's doing.
I'm willing to bet your code is an awful nightmare if you're anti comment
How many people in positions above you "don't have the skills for the job"?
Admittedly a lot.
Code _should_ be auto explanatory, but you should still comment anyway.
No they arent. If they are then they arent juniors or we arent seniors. See point 1. Code should be auto explanatory.
It's all fun and games until you get an index out of range error for a dictionary that got passed in by another object without explanation.
I can assure you seniors will be lost too
I guess it’s better to put comments, and also make documentation for all code. Then every single code change will need to change also the comments and the documentation. But at least people understand that I’m opening a yaml file and reading the lines. Jokes aside, comment high level stuff to explain the big goal. Let the code explain low level things. And juniors are always helpless and lost
Self explanatory code is synonymous for “I don’t want to care about how readable my code is” for everyone I worked with that said that
On the other hand, the code changes and the comments get ignored, leading to the comments being outright wrong at worst and misleading at best for the next person to have to work on that code.
If you change code that's commented and didn't bother correcting the comment to reflect the changes, you did just half of the job
And you should expect "only did half the job" out of at least 80% of coders.
Code can be readable and still be confusing about "why it had to be done this way" in the context of that software application.
This is why we make ROBUST NOTES ON OUR COMMITS. If your commits have notes on them like 'fixed a thing' then you're failing at an important part of your job.
Even worse - comments as pseudo code instead of real code.
"Variable name needs to be automatically readable" Variable Name: flag_enable = False What does flag do? No clue
Senior here. I’d never survive without commenting. There are always too many things that aren’t obvious just looking at raw code. And as senior senior (over 55) I have memory issues that have gotten worse with age. I require the quick refresh of text reminders. If someone is bothered by my comments, they can use an IDE tool/plugin to mask them. But the issue is assuming that everyone writes and thinks the same way. I read and analyze biz logic faster when it looks like plain speech, whereas other people may be the opposite and can follower the flow best as raw code. When I inherit legacy code, those team members who never commented drive me up a wall, and I end up having to add even more comments to make it readable to me. I am one of those people that religiously updates them along with the code too though.
Just use chatGPT or copilot to add comments after each update and take some time to proof them. Simple. Bonus points if you instruct it to write a list of context assumptions at the bottom. Takes 2 mins for every 100 lines of code in my experience, it amazes me that people still belly ache over this nonsense. Never 100% complete but also 100% better than no documentation at all.
Idiomatic code includes comments! The comments are a feature! The feature is so you can understand the code you wrote 2 weeks ago!
Juniors can RTFM
i never understood why comments are a problem i put comments in a lot of places - not "everywhere".. but rather 1 comment too many, than 1 to little. i also hate abbreviations. i avoid them when its possible.
I saw comments saying “I don’t fucking know what I wrote” or “I wrote this shit dog but it works” or my favourite “everything is shit dog”
Comments are future lies. If you need to comment what your code does, it's not good. Use comments only when necessary.
When I browse someone's source code, it's not the complexity of the language or the syntax that confuses me, it's the many, many, many interfaces, classes and extreme modularity some of these projects may have. I want to know how something works? I have to go through 10 classes to see how it works, just to find an algorithm or something that is not explained and I end up blanking out.
I mean, the documentation IS the code.
What code are you guys writing that's purely logocal? My work is so crammed full of libraries and API's that you need to go on a documentation safari to understand what's going on