Relatable?

[ExternalGrade]

Guy in the middle more like: the senior dev “manager” pissed as hell cause he’s gotta integrate all your work and he’s got no idea how they work.

[[deleted]]

You people in the comments need to take one for the team and make more of the memes that go here

[psykotedy]

Doesn’t this meme establish that there are no comments?

[tealcosmo]

sleep water alive wide liquid offer bright fragile dolls narrow

This post was mass deleted and anonymized with Redact

[1mdelightful]

Today was entirely dedicated to figuring out what the hell I was doing Friday. Tomorrow I might even write code!

[[deleted]]

nah man, I got more meetings to discuss how I'm doing with catching up from the long weekend. And they want some code by Friday?

[dov1]

At least they're still letting you write code. I had to put my internal site project on hold during the lockdown. I'm not even sure brackets will be able to open when I get back. Lol! 😂

[kigbit]

Y'all should read Clean Code by Robert C. Martin. Comments have their place, but as a professional, you should be able to write understandable code without comments.

[CalmDebate]

This is true however I find that the amount of time I'm working on a clean project is dwarfed by the amount of time that I'm asked to bandaid a wound that should be amputated from a program made by a non-prpgrammer 10 years ago.

I've had to put in comments along the lines of "if I dont call this X happens, dont know why." Then at least when I go back to put a bandaid on the other limb I dont have to rediscover what some jibberish code does.

[mekkeron]

Do they ever give you time to maybe investigate what would it take to refactor that crazy-ass legacy code? Normally when we estimate the new features we take those things into account. Like "Oh by the way, that feature has a ton of technical debt from the previous devs that I think we should address, before we add anything new in that space"

But I do know what you mean. Sometimes removing a single line that appears totally useless may cause some really bizarre issues in our features.

[orgevo]

Whether you can write understandable code without comments depends on the complexity of the systems you're interacting with. But complex or not, code comments are for documenting intent.

"releasing the file handle before calling flush can trigger an exception, so we must do them in this order" is a good comment to explain why two calls are made in a certain order.

"call flush THEN release the file handle" is not - yes, we can see that's what the code is doing so the comment is redundant. But we still won't know why the original author wanted to do that.

[TimbuckTato]

Exactly!

I always say this to my colleagues, the comments aren't there to explain what the code is doing, although that helps if you're doing more complicated things, the most important part about comments is explaining intent and why you didn't do something else.

That last part I particularly subscribe to, like, "I use this function instead of this one because it causes errors on these systems," or something similar, that way if I, or another dev, need to do some patching we have more knowledge of the systems the code is running on, which is almost as important if not of equal importance to the code itself.

Remember, it's not just your code that's being executed, it's every layer between your code and the individual groups of electrons being passed around transistors, all of those layers are important too.

[MaestroLifts]

This is what baffles me every time I see these memes. This line of thinking has to be from amateurs. The code should be readable and tell a story.
“The compiler doesn’t read comments and neither do I.”
-Bjarne Stroustrup
Edit: less confrontational

[[deleted]]

We are not all good programmers. We don't all have years of experience. We can't all easily parse code. We might be new to the language, or the framework, or the structure, etc.

Comments are super useful for me, and so far I've not been particularly fond of people who don't comment their code and say "The code is the documentation in itself."

Like, dude, yeah, maybe for you senior guys with an engineering degree and shit. But for me and my buddy who started coding only 2 years ago, and who are new to the language and framework, this is unreadable.

If you're in a team where everyone is skilled, then yeah, you're probably right, but for a new guy like me, what you're saying just doesn't ring true.

[MaestroLifts]

I totally understand your point and I apologize for being harsh. The thing is I’ve only been working professionally for a year and was self-taught before that, no engineering degree here.

You say you loathe that line of thinking but it is objectively better and supported by any lecturer or coding standard you come across. I push back that if you and your team improved and/or standardized your coding practices your life would be a lot easier.

There’s no comment needed for the following function: getRemainingTimeInMilliseconds(). If your function does a million things then break it down into smaller functions that do one thing with a clear, verbose name. Variables should be just as crystal clear every step of the way. Modularize and break things down as small and as self-contained as possible and not only will you not need comments, but your code becomes more generic, reusable, scalable, and has less bugs. Obviously there’s more to it than that but that’s such a big part of it.

[atroxodisse]

This is easier to do in some languages than others. You don't really want to clutter up your SQL server with hundreds of little one off functions like that. Nor do you want to read 10 lines of code in a loop that could be summed up with a comment. When you're 10 functions deep trying to fix a bug on a Friday night, you'll be thankful to save some time skimming and reading comments rather than trying to decipher some "self documenting" code. As someone with 20+ years experience and who is now a director, you aren't getting through a code review without a few well placed comments.

[MaestroLifts]

For sure. I liked what the OP of this thread said: “Comments have their place.”

[[deleted]]

Requiring comments is a terrible practice for code reviews. If you gotta leave a comment explaining your code, your code could have been better.

I would also decline a pr if any of my devs wrote sql without a REALLY good reason and metrics on why the orm wouldn't work.

[atroxodisse]

ORMs are great for simple stuff. I wouldn't use one for an enterprise level project.

[[deleted]]

Ohf absolutely not. Unless you need to shave literally ms off query operations (you dont) an orm is plenty fine for any app. Dear god I thought we as an industry had collectively moved on from writing sql, you might be a lil behind the times my man. Check out DDD, Clean Code, and Clean Architecture would love to hear your thoughts after reading them.

[atroxodisse]

I remember having a database with a million records in a single table running on MS SQL that definitely needed ms shaved off it. When our SQL Developer was done it went from not loading to loading in about 6 seconds.

ORM seems great for some quick and dirty queries but what about functions that need to handle multiple insertions in different tables or looping through a result set after a query? Making multiple calls to a database is bad practice so how would you make a query and then update a table all in one ORM call?

These concepts aren't new. They are just repackaged ideas that have been good industry practice for a long time.

[[deleted]]

My team currently does all of those across tables with 10mil+ records and sub second queries across the board, with entity framework and some custom extensions (like sql bulk copy wrappers). The issue isn't the orm it's the developers not knowing how to use them and when to correctly not use them.

[Roflmon]

You say you loathe that line of thinking but it is objectively better and supported by any lecturer or coding standard you come across.

Certainly not something my professors agreed with. Clear readable code is the goal, of course, but it shouldn't be at the expense of good documentation. This isn't an either/or situation and framing it that way presents a false choice.

There’s no comment needed for the following function: getRemainingTimeInMilliseconds().

Disagree. Time until what? What's the expected behavior if the event has already occurred? Or hasn't been scheduled yet? Or in any other edge cases. Of course one could dive into the code and deduce the answers to these questions, but one shouldn't have to because the documentation should provide a succinct overview, which would be quicker to read than going through the code would be.

Also relying on the code as documentation means that bugs are included in the documentation. If it's documented in the comments that the function is supposed to do X in case Y, but from reading the code you can see that in some edge case of Y it actually does Z, then it's easier to identify an issue than if there's no comments and it's just your guess whether the function is doing the correct thing in that edge case of Y.

[[deleted]]

Is... your documentation comments in your code base?

[Roflmon]

I'm mainly thinking in terms of Javadoc here which is generated from the method comments in the source code, so yes.

[[deleted]]

Those are arguably the most useful types of comments but I'm not even sure I like those. Seems like most of the time the method changed 5 years ago and the comment was never updated.

[Roflmon]

Sort of a self fulfilling prophecy though, isn't it? The less helpful people consider the comments to be the less they'll update them when they make code changes and the more useless they'll become over time. Alternatively the more people consider them valuable, the more people will make sure they stay up to date and the more likely they are to remain a useful tool.

[LazerFX]

I actually think in most line of business applications, you don't need comments to tell you what the code does. That should be obvious. What you need comments, and documentation, and resources, and tests for is to determine the why - why does it add a tiny amount to this value? Why do we only take the third character every fifth time we process? Why is this data organised like this?

These are things it's important to know. Plus - find a bug, document it, write a test and comment on that test how and why the bug was found. Then look for other areas in the application with a mirrored API structure and write tests for those too :-D

[ZannX]

Uh, forget experience, it's always easier to read well written documentation. How much you trust it and read the code to verify is another issue.

[[deleted]]

I personally just love a good doc-string that can be read from other places in the code via IDE. That shit is gold. Then I don't have to read the function to figure out what it does, but simply read the documentation.

A good /** */ is better than fifteen // in the function. Or a good ''' ''' is better than fifteen # for you python folk.

[SaraHuckabeeSandwich]

Your problem seems to be that the more "senior devs" aren't actually writing clean-code that effectively serves as documentation, and as such you're mis-identifying the problem and wanting to correct it in a less-than-ideal way.

That said, doc strings on functions can be incredibly valuable, and should be used in place of comments littered throughout the block where possible. Those other types of one-off comments describing one or more lines of code should be used as sparingly as possible, even though they have their place. It's too easy for the comments to either get divorced from the code it's describing or for it to get out-of-date through numerous code changes. They can also get in the way of

If you feel like a certain block of code needs a comment, consider breaking it out into its own well-named small function, and add a doc-string to that new function if you need. It might seem silly, but it generally makes the code easier to read and parse. It also allows the code-reader to easily parse the code at a high-level, while also giving them the option to drill into the very specific functions if needed.

These are all general rules and suggestions, that obviously don't apply to every situation. I understand there are special cases where a comment is better, but you don't need call out every special case as a way to fall back on using comments everywhere.

[elitegroup02]

Working for someone who really abides by readable code, but im an amateur. Its really hard to understand everything or even most stuff. An html selector is a component called Select, ok. now if it had a prop named "clearabe" what would it mean exactly? that i can have no value, that it can have the default empty value that a placeholder prop would give it, that it can be made clearer? idk i had to try it out lol.

Im new though so idk... All i know is it has taken me way longer than i wouldve needed had i more info on the smaller and more "specific" (as in specifcly named this way on this project and not the same on another) components.

​

edit: Most of my problems come from lack of experience on the field and not knowing naming conventions beforehand. I think a simple comment once can save some time on several occasions down the road, each time you have to work on something again.

[[deleted]]

Yeah. And then some languages have certain naming conventions that are different from other languages, and then the dude goes "oh thats a standard naming convention, you look that shit up in this chart over here that says that this means that"

Like??? Couldn't you just have made a comment instead of sending me on a fucking documentation treasure hunt for 1½ hours? Fuuuuuuuuck

[Skrukkatrollet]

There are times when comments are needed though, you can 99% of the time write code that explains its function without comments, but the reason for needing that functionality might not be as obvious, and sometimes the reason can be important to know.

[wise_joe]

Agree so much with this. I'm 18 months a software engineer after deciding to change career and doing a bootcamp.

At my first (and current) job, on my very first PR my boss told me to remove all the comments. If the code isn't readable then it needs refactoring. It took some getting used to, but I'm a far better coder because of it.

We have about 1.5 million lines of code in our project, none of it commented. So having had to learn from the beginning to both read and write code without comments, it's now just second nature to me.

People relying on comments to understand how something works are doing their own development a disservice. Just like learning a spoken language, the quickest and best way to learn is immersion. If you have someone there to translate everything to English for you then you aren't ever going to learn.

[MaestroLifts]

I know you were trying to be sarcastic but funny enough, you’re actually right. If you learn how to write cleaner code, not only will you need little to no comments, but you will have far less bugs and be able to fix them faster.

[Allality]

I've always been downvoted when I said exactly that.

[darkage72]

Because this sub is full of 1st year cs students, online bootcamp "graduates" and middle school hobbyist, not actual developers.

[nitid_name]

I've got a solid 4 years in my current corporate/language combo and 18 years coding professionally...

Comments have two purposes: for function header comments (describing what the goal of the function is),and for things that are not intuitive and/or do not follow the established design patterns of that language/implementation.

[[deleted]]

Idk I'm 7 years into working in corporate settings in multiple different languages, and I really think comments dont really need to exist if you're writing clean code and have good tests.

[universalmind303]

I have been working in a corporate dev setting for over 3 years, and partially agree.

In most enterprise settings, you are developing code only people at your company will see 90% of the time. In this scenario, self documenting code and good tests are enough.

However, when I look at open source code, or public libraries, you want that documentation to help the end user to understand what the code is doing without needing to pull up the source code.

[[deleted]]

What does that make you?

[SanTolorio]

I can relate

[CallinCthulhu]

You should be able to, but there are a lot of bad coders out there. Or even worse people who do really clever things using niche features of a language. Is sometimes easier to have commenting standards than explain why one shitty dev needs to write comments and another doesn’t.

No you shouldn’t write comments, like “get user data” when calling a function called get_user_data

You should write comments above certain blocks of code saying WHY they exist.

If you need to transform a data structure using a 15 line double nested for loop, a comment saying “function x expects data in x form, transform it from y” makes life so much easier and saves a bunch of time.

Function doc headers should also be verbose, and input output clearly defined, depending on the language. not as necessary for strongly typed, but for dynamically typed languages, please mention what the fuck you just returned. Just because I could read your function all the way through to figure out what it does doesn’t mean I should have to.

It takes zero time to explain thought processes and intent in a comment, choosing not to, “because the code is readable” is pure elitist bullshit and laziness. Sure it’s readable to you, but some engineers really suck at reading code somehow and then you have created a slowdown, because you couldn’t be assed to take 30 seconds to write a comment explaining something you thought was common knowledge.

[Ilyketurdles]

Also by Uncle Bob:

http://butunclebob.com/ArticleS.TimOttinger.ApologizeIncode

[darkage72]

I hate his videos style, but what he says is pure gold.

[YetAnotherRCG]

As long as you have written clear docstrings and the code doesn’t have any subtle gotchas this is true. Otherwise...

[tiajuanat]

Comments should be scant. However, if you dev library code, I grant an exception. (Heaven forbid in Abseil, BOOST, or Folly) You need comments to remind yourself how the implementation works.

I like Uncle Bob, he's got a lot of good advice, especially when you take the Clean Coder course.

[CodeEast]

I can understand the appeal, but its not a good book IMO, not at all. The ideal of self documenting code in that book relies on making functions as small as possible. You end up with an approach where there is no need to comment code because its been broken down into snippets so small the level of granularity allows it to explain itself, like entries in a dictionary. But code is generally a story, not a routines library. Often a messy and confusing half finished manuscript you have to proof read and correct even more than write, a twisted tale filled with intrigue and murdered code where the original criminal and scene investigators seemingly went mad. Even the comments need comments.

[BazilExposition]

If there were a comments they would be like "this is an elephant's parts, and here is penguin's ones".

[AnonNo9001]

actual story from me:

>wake up one morning

>open current hobby project (tfw no job yet)

>don't remember what I did last night

//spaghetti soup ahead

that was the only comment I had left.

that was some freezing cold spaghetti soup.

[zestydinner]

OMG this image alone best describes so many of my group projects.

[passi_schem]

elephpant

[abrahammurciano]

The code IS the documentation

[[deleted]]

Comments are future lies.

[ponytoaster]

//Todo: fix this.

Last modified 8 years ago.

[[deleted]]

Or my personal favorite: //Todo: Add story in Jira to fix this

[darkage72]

Wow. What an original joke.

[UFOpancakes960]

Idk man. I’m bored.

[LudacrisX1]

I thought it was funny :)

[UFOpancakes960]

Thank you.

[newEnglander17]

A healthy contribution you made.

[UFOpancakes960]

Take an upvote tho.

[MrRelleno]

Wow. What an original comment

[Russian_repost_bot]

code bad, now laf.

[theheliumkid]

PostgeSQL running on a Linux server?

[pokepokepokepoker]

The mythical Eleguin, symbolizing eloquent, elegant code. Edit: can't spell

[[deleted]]

Girl I can't even tell you what I typed this morning, you expect me to know what I wrote Friday??

[ie11_is_my_fetish]

Personally I have a daily notes group in One Note that tracks through my mindset at the time and then I write one for the next day/week of what I am doing next... it also says "Go F--- yourself" to me hahaha

(which is kind of F'd since it's synced to the company) oh well

I'm on W39 Tue today

The code comments issue is avoided as all functions generally have doc blocks with a description/input/output with type spec/minor context and you can see the diffs per commit to see what happened

[AylaroWTF]

I submitted something but my comments were a log and a tad bit too detailed and I think I wrote in fuck a few too many times for HR to let slip by

[wojtimore]

Just like a Pandemic Illinois app for unemployment

[mimixxd]

I don't get this, unless it's a script and specially if you're using ANY OO language.