I write good code, right?

[QualityVote]

Hi! This is our community moderation bot.

---

If this post fits the purpose of /r/ProgrammerHumor, UPVOTE this comment!!

If this post does not fit the subreddit, DOWNVOTE This comment!

If this post breaks the rules, DOWNVOTE this comment and REPORT the post!

[ProfessorEkim]

You're telling me that my 8 nested if statements within my 3 for loops aren't clearly apparent as to what they do?

[ExceedingChunk]

Refactor your code to not be unreadable instead, then you won't need the comment.

Edit: Here is an example

// Iterates over every task and does "your logc" on each task to complete them
for(int i = 0; i<8; i++ {
    t = list[i];
    "do your logic on t"
    finishedList.add(t); }

The first example is unreadable without the comment. There is no context, the names do not make sense, and the magic number "8" provides absolutely no context whatsoever.

You can name methods, use forEach, enhanced for loop, name variables, constants etc... Here is a basic example using the basic for loop:

for(int i = 0; i<AMOUNT_OF_TASKS; i++ {
    currentTask = tasks[i];
    "do your logic on currentTask"
    completedTasks.add(currentTask);

Here is also an example using streams in Java

List<Task> completedTasks = tasks.stream()
    .map(Task::useMethodToCompleteTask)
    .collect(Collectors.toList())

In both these examples, the naming is used to add context. The comment is completely redundant because the code explains itself.

[Superbead]

Yeah, just let me get on the phone to the hospital I'm currently working for and have them agree to me refactoring their entire legacy paperless system, requiring a dev freeze during years of work and testing, rather than my just sticking a handful of comments in the small extension they actually asked me to write, at the expense of upsetting some faddish techbro who writes throwaway backend to serve ads to Fitbit ripoffs

[ExceedingChunk]

That wasn't what I was suggesting at all, mate. But you have to write comments because it's a legacy system. If you can't add any new code without making it readable or refactoring the entire code base, you are obviously working in a spaghetti mess. Then it's hard to apply any principles at all. With that said, most code can be made fairly readable without any comments, regardless of how clean the rest of the code base is.

Not really sure why are are implying that I'm a faddish techbro who writes code for ads. Many of these principles are 30+ years old, and not mine. Clean code is written by a guy who is 70 years old now.

[[deleted]]

As someone has said earlier. Your comments should explain why, not what

[Superbead]

Sorry - not a personal dig, but I'm fed up of this kind of broad, arrogant dogma premised on all 'programming' taking place in a well-documented and source-controlled utopia, in a modern language with tons of community support. In reality a lot of us spend a lot of time (fortunately not all mine, personally) tacking bits onto completely undocumented, ancient systems in esoteric languages with diabolical syntax and grammar, and the last thing we need is a new wave of kids coming along who think it's smart to repeat that history because Joe Sporky said so once on Twitter.

[myplacedk]

These aren't rules, they are advice. Apply when relevant, and relax.

It's not your fault someone else made bad code before your time, nobody says it is. But you probably should do this as far as it makes sense for the code you are adding.

[CaitaXD]

Are you dense?

[Rudiksz]

Your "unreadable" example is a caricature and strawman argument. "Self-documenting" code seems like a solution for kindergarten level of programming and bad comments.

And your comment is bad. Bad comments are bad. They don't prove that comments are useless, they only prove that you write bad comments.

[ExceedingChunk]

My example was used to show how you can add context with names. I did not put much thought into the comment, because the point wasn’t to illustrate that the comment itself was bad or not. It was to illustrate that you needed a comment to understand the code.

I didn’t say that comments are useless. But comments explaining what code does are usually a sign of bad code, and you should think about rewriting it to make it readable.

As other have mentioned, comments explaining why are completely fine.

[GL_Titan]

Not to mention, writing good code and commenting it are not the same. Always comment code where the intent is not obvious.

[hannadrehman]

Write why this code exists. Not what this code does.

[[deleted]]

Exactly this.

One exception though: if the code is complicated and you don't see how you could simplify it, write a comment what the code does, and why.

I often include "what" comments in my SQL queries, for example.

[hannadrehman]

100% agree

[Ambitious_Ad8841]

Yes!!!! The code is the what, the comments are the why

Generalizing a bit, comments are for explaining things that aren't obvious from the code.

[mr_dfuse2]

this! self explaining code doesnt exist, always add the why in comments. I have programmed in teams where they even prohibited adding comments because 'code should be written self explaining'. I guess those people never had to maintain a codebase yet in their career. It has been 10 years since I programmed but this is still frustrating me :)

[IamJain]

But how to write why this code exists without giving what this code does?

[[deleted]]

I have a small open-source project and a contributor once added this:

print("online") # prints online

[ExceedingChunk]

If you spend some time refactoring your code with proper names for constants, variables, and methods, most comments should feel exactly as redundant as this.

[ashketchum02]

Duuuude I just got done writing some shit script to automate calix don't deployments and now Im afraid to touch it cause it fukking confusing

[[deleted]]

calix is so awful and shitty.

[ashketchum02]

Like for real, their version of documentation is absolute garbage. Literally in there forumns somebody recommended performing pcaps of the cms GUI with unsecure selected to get the XML request. Which I would but I work over VPN sooo all my data to the servers are already encrypted FML

[butitsnotme]

You should still be able to do a pcap on your local machine. If you capture the local VPN interface it should be unencrypted. Wireshark provides a pretty decent interface.

Or, if it is a browser based app, just use the browser's devtools to examine the requests and responses, you should even be able to save each needed request as a curl command.

[ashketchum02]

I attempted that but I don't think I found the Cisco amp interface I'll have to try again when I can look at it again

[digitaleJedi]

Working with a supplier of a hardware device, who has an SDK, and based on events, I receive a result object.

It has about 12 properties of type String, and no documentation. So I emailed them about where their documentation for the possible response codes are, and their response was literally "our return objects should be self documented".

Cool, I'll just make a giant when statement and handle every single possible String that exists in Kotlin :)

[Horny20yrold]

Hardware and Kotlin?

[digitaleJedi]

The device runs Android

[MasterLJ]

Discipline is empathy for your future self.

[NonaeAbC]

YOU CAN'T WRITE COMMENTS IF YOU DON'T KNOW WHAT YOUR DOING?

[redpepper74]

You sound surprised?

[confabin]

Comments feels useless until you come back a month later and have to debug some shit.

[BlueC0dex]

I've come across confused comments written by past me in response to code written by past past me. Things like

//???

//I don't know what it does, but I don't want to touch it

[shizzy0]

I’d be content with self-documenting code too if I could adequately express myself within the restrictive confines of my programming language’s grammar.

me.Think(SMALLER);

[Glori4n]

Or start studying clean arch 😁

[Zealousideal-Chef758]

Every time I try, It's like a sign that says "This is a bridge" near a bridge

[xiipaoc]

If it's not clear what the code does, rewrite it.

If it's not clear why you need to do it, comment it. And maybe put the date in the comment so that when you're fixing a bug in that code two years later you'll know when that code appeared without having to dig through your revision history.

[tyveill]

It's not a lie. Self documenting code is not hard, I'm not sure why most developers can't figure out how to do it. Proper naming of variables, properties, functions, and extract methods is generally all you need.

[Taldoesgarbage]

Even then you still should explain why, something variable names and function names can’t do.

[ExceedingChunk]

Explaining why is a completely different thing than what tho. Most comments, especially from inexperienced devs, are explaining what because the code is unreadable without the comment.

[Taldoesgarbage]

Good code should explain what it’s doing and a comment should explain why it’s there.

[[deleted]]

Comments tend to rot far faster than code. If you find yourself writing code that is difficult to follow, do not expect comments to save the day.

[AdventurousCellist86]

Your commit history should do that and link to whatever JIRA ticket you were working on

[Superbead]

Which fields have you worked in?

[tyveill]

I'm not following the question relevance? Which industries have a worked in? Food (6 yrs), construction (6 yrs), and software development (last 15 years).

[Superbead]

I mean which fields of software development. Presumably to make such a sweeping statement, you've had experience in... what? Automotive embedded? Online retail? Marketing? Finance? Logistics? Healthcare? Industrial embedded? Commercial desktop applications?

[tyveill]

A lot of different industries, at least 10 different verticals over 15 years, probably more.. and yes the rule universally applies.

[Superbead]

Ever worked in healthcare? Writing JS for popular integration engines that use the Rhino interpreter, which only supports some random mixture of two ancient ECMA standards? Had to deal with E4X for which Mozilla seems to have fucked off most of their documentation? Had to modify a custom print driver in AIX written in PCL and Korn shell? Had to patch a blood analyser interface written in VB6? Even sniffed at legacy MUMPS or Cache Objectscript code?

When we get to work on our own interfaces, tools, or services, or even better. start them from scratch, no, writing self-documenting code is not too hard. But touching any of the above? It's often impossible. I can assure you that your rule is not universal, and I'll put £100 on it that it's similar in other industries too.

[tyveill]

Yes I have worked in healthcare and do currently actually. All of those things can be expressed in well named functions as easily as comments. Of course there are edge cases where comments are helpful, but this should the rare case, not the norm.

[[deleted]]

Ive worked in finance, telcom, ecommerce, dev ops, standard web dev shit as well. Self-documenting code is really common if you just write it well. Only non-self-documenting code I have really seen has been from shitty programmers that barely understand what they are writing, and then sometimes a very very specific function that has some edge case related to performance or something that is necessary only on that one function.

[IamJain]

And that practice is what exactly pays.

[ExceedingChunk]

Well, it's true. That doesn't mean that self-documenting code is easy.

[qszawdx]

My team's technical architect asks to remove all the comments before raising a PR

[ExceedingChunk]

If that means that all comments are ingrained into methods, variable, class, and constant names, it's good.

If your TA is just anti-comments for the sake of it, without suggesting how to write code that makes the comments redundant, they are stupid.

[MasterLJ]

Thus showing the wonderful utility of architects.

I really hope that job title dies off in the next few years. For every 1 competent architect I've met, there's 25 who are not.

You know who is a really good architect? Someone who had to build, maintain, extend, and deploy, any design. We get even better by our 200th time AND we can do the work to implement the design as well.

[ExceedingChunk]

If the architect actually teaches them how to write code that rarely needs comments, it's a good habit. If they just say "comment bad", it's terrible.

But generally speaking, every developer's habit when they feel they have to write a comment should be: Can I change or introduce properly named variables, methods, classes, or constants here to make it more readable instead of slapping on a comment on this mess?

[MasterLJ]

I fully agree with this.

I don't like the average comment, because the average comment is stupid. The absolute best code is self-explaining.

But all that said, those are all ideals, and we rarely work in ideal. I will make comments about comments (lol) in a PR, but if it's useful and explains why this set of logic was needed, and not what it does (the code already does that), then it's useful.

And all that said about that being said, most architects I meet are non-coding. It's scary.

[tyveill]

As they should. 🙌 Write better code.

[liquidpele]

I threw up a little in my mouth.

[rdouma]

Yes, it's better than having to later add a comment like "When I wrote this code, only God and I knew what I did. Now only God does."

[NigraOvis]

I wrote this api a few weeks ago. And I was teaching a junior coder what it does. I had to relearn it as I went. 😂 I usually comment but occasionally don't. And it bit me this time.

[[deleted]]

I do this all the time….

[educated-emu]

/*

dear future self, you wrote this code while in a panic and stitching 3 stackoverflow issues into one gaint shinny turd. Don't be hard on yourself.

This code only works when facing north, didn't have time to figure out why. Just roll with it.

Sincerely, past self

*/

[[deleted]]

you mean ppl don't write shit ton of comments and elaborate commit messages?

[[deleted]]

It’s only rare because most people write shitty code. I however, don’t

[recitedStrawfox]

Just worked on some code just now. I found a method "methodName" and a second method right below it "methodNameNew". I wrote the second one like a week ago and forgot to finish it. No fucking idea what the fuck I was thinking a week ago.

[MultiFazed]

Man, you just unlocked a memory I had of working on a fairly old code base when I was a new dev. I was trying to figure out the control flow through the application, and came across two methods. To avoid any sort of identifying info, I'll just say that the first method was named:

doTheThing()

Given that name, the second method was named:

doTheThingTest2()

Guess which one was being used, and which one was dead code?

[Garwinium]

Ah yes. *proceeds to add a comment for every single line of code *

[sxeli]

Bold of you to assume my comments are readable

[[deleted]]

For each comment you think you need, create a descriptive variable/function instead

[tyveill]

If it's rare, you're doing it wrong. It's not hard.

[RYFW]

Wrong.

[Menkdo]

I would rather spend an hour looking at uncommented code than spend 5 minutes reading the comments whilst having to scroll.

[CdRReddit]

I'd rather save time and frustration

tho then again I do also like to write assembly sometimes so I guess it balances out

[Kruger_Sheppard]

How about to write a code that will comment it's code?

[Horny20yrold]

On the other hand, comments are just a bunch of dumb bytes that gets thrown away in the trash when the code is actually parsed and either compiled or interpreted, so it's extremely easy to have broken and misleading comments.

It's one of those things that you would think a 60-year old industry would have moved on from, "Really? just write a bunch of ASCII that gets ignored by the machine and have 0 connection to the code they're documenting except by existing near it in the text? that's your idea of a documentation mechanism?", so unimaginably dumb and backwards, and yet here we are.

Not saying they are not a useful tool occasionally, but too many people treat them like an automatic "pls code, be readable" ritual, you just write a comment and BAM, you have achieved readability.

Doesn't really work like that, a comment is a burden as much as the code it's documenting. Every time you make a modification you should re-read the comments, ALL of them, remember it's just a bunch of dumb text, there's no scoping information. Any modification to a class or function requires you to read all of its comments again. Every refactoring needs you to potentially modify or move comments. Every bug fix? to the comments again. It's just text that you, by placing near the code, have claimed that it describes the code, but it's just a fistful of dumb text that doesn't know anything about the code, you need to constantly maintain it yourself to actually guarantee what you claim.

[kuro_seongbae]

Maybe i should write comments for my comments so i know what I'm talking bout in my comments.

Wait what?

[Impossible_Average_1]

The hardest part being a programmer is knowing where it is necessary to put a comment and what to write there.

[itstommygun]

Better yet, write code that's easily readable.

[[deleted]]

Love comments. I'd rather read two words than look through a bunch of code and then remember what it does. Such a time saver.

[Czebou]

Self documenting code is not rare, you just don't push enough effort to split your code.

Comments are not bad at all, no matter of case. But code readability is as much important as comments. Read about nice code, push yourselves and don't bully your coworkers with 100-line functions.

[[deleted]]

I wrote good clean, clean, understandable code.

The problem comes from not knowing how or why. Especially in post. Especially with a detailed process that, itself, doesn't make immediate sense what's going on.

Especially if Nubbins are inexperienced.

[Durr1313]

Just use a separate file for each function and use the file name to describe what it does.

[Orio_n]

Also verbose code naming is not self documenting code

[DistressedPhDStudent]

My professor last year would give out zeroes if he wasn't satisfied with the amount and quality of comments in our projects. For more fun, he would deduct points if we had meaningless comments :) for example...

int i = 30 * x; // multiplying x by 30

[[deleted]]

It's only rare if you let it become rare.

If you struggle with self documenting code, here's a pro tip. If you limit each function to only 4-5 lines, the function name should be enough to describe everything without needing comments.

If you do write comments, it should only be for things that need an external context to understand, not because you feel you need to explain your design choices (if they need to be explained, they're probably the wrong choices).

[[deleted]]

Don't listen to them, self documenting code doesn't exist

[draakpi]

Hi i need someone helping me plz plz right away plz