Starting to notice a trend that people who don’t write docs and say “the code documents itself” tend to write the worst fucking code imaginable.

Like how can anyone read what the fuck you are doing if you misspell everything you dumbfuck

"iT's SeLf dOcUmEnTiNg"

meanwhile, in the smeagol-dungeon:

// this class does stuff

class HorriblyMisnamedClass { /* code */ }

@swagnette I wish they wrote comments too. Not a single comment throughout thousands of files

@phat-lasagna I recognize this way too much tbh.

No comments and "self documenting code" with methods like "getAuthenticatedUser1" and "getAuthenticatedUser2" with completely different logic behind both of the methods.

@swagnette yeah like I get it’s frantic and nervous, but I feel like all early shitcoded business logic has a devastating butterfly effect.

@phat-lasagna Very true

Writing docs is often a sign of a rigorous person, so you can easily extrapole that to people not writing clean code or being lazy overall

I see it that way:

People who write unreadable code will also write useless docs for the same reason that they fail to write readable code.
They will just slap some comment on everything. Which hardly makes it better because you could as well just rename that thing instead of adding that comment.

You know how comments should answer the "why". Not the "how" or "what".
And by incentivizing to write comments and docs everywhere, you will mostly do the wrong thing.

The problem is not the lack of comments and docs. The problem is that people don’t know how to write readable (self explaining) code.

Learning it is hard.
It’s not as simple as slapping a comment to each line of code, but it’s the only way to really make things better.

If this is as real as the post suggests, then man am I scared to switch projects/jobs now.

@Sid2006 yeah I’d say just be really careful lol

@Lensflare I honestly think it’s just people with no empathy or work ethic that code to get money. They have no interest in making the experience tolerable for others or improving themselves.

There is always a balance of docs enough.

@gosubinit yeah true

What about Markdown lol

I am in self documented code camp but I put comment on what the method does, what values the parameter expected and what output it return, and what you should expect on invalid parameter.

You may not know how the method does thing but you know what the method does. I only document my code if I does something "clever" since I am lazy to update document and code at the same time. I believe that document get outdated really quick if you do not update it the same time as your code. My opinion is wrong document is worse than no document.

@mr-user agree.
And if you are using a proper programming language, you can (and should) encode what values are valid into the type system so that you don’t even need to specify that in comments for parameters and return values.

In most cases that will simply exclude null/nil but you can also go beyond that. Making invalid states unrepresentable.

@Lensflare you do actually because it's often unclear what that Boolean or integer entails. Or what the value is when an error or edge case occurs.

@phat-lasagna I'm kinda understand where it comes from and agree with the original idea but not the blanked statement. Code is ideally readable and does not require a slew of comments or documentation everywhere. A whole manual on every minute detail does not help and gets outdated. The code does not. The general ideas and concepts must be documented just as the API. The higher up the more documentation.

If you feel the need to write a comment perhaps you can make the code clearer. They way of writing self documenting code can be good behaviour but even then it's tricky because not everyone has the same idea behind the same words. I had that issue with debounce a few months ago. Implemented it, all methods properly named. But colleague never heard that it was called that way so it was super unclear for him.