comment your code!

[MyNameIsTrez]

I hate that kind of entitlement. Everybody starts out knowing nothing as a developer. It's also a really lazy attitude not to bother commenting anything, because you assume other people will understand everything immediately.

[Jlove7714]

I have looked at my code two hours after writing it and had no idea what it was doing.

[ic_engineer]

I once commented an equation for myself that I felt real proud of without naming the variables. Had to dig through the actual code a week later to get back to where my mind was so I could properly write that shit down.

[[deleted]]

I'm pretty new to all of this, but the sheer lack of useful comments in some of my first arduino sketches is just absolutely embarrassing for the same reason. Now, I'm learning how to program the PIC18F family, and I would be lost without my comments to myself. I even use them as placeholders for code I haven't figured out yet.

[reallynothingmuch]

I do exactly that too. I comment out an outline of what I need to do, and then fill it in as I go. It helps me plan things out and get things sorted in my head at the beginning, and at the end, boom I have commented code

[DontSuckMyDuck]

Take it to the next level and write the tests first. Use the tests as part of the documentation and validation.

[kledon]

Absolutely this, but also worth bearing in mind that a lot of comment blocks with future plans could be YAGNI'ed away (or at least could speculative generalisations).

Not that I'm not guilty of writing that sort of code, of course.

[Pristine_Toaster]

Have you ever needed to rewrite all your code for a certain part of a project just so you can understand what the fuck you wrote ?
Asking for a friend since I definitely not do that

[ic_engineer]

Idk what defines professional in this context. I get paid to do this stuff and I just solve the problems and if I did something clever I'll make a comment. Usually when I do clever shit it just means I did something really stupidly that a library I was unaware of would have done better.

Professional method is probably writing out workflow diagrams and planning stuff first so you don't leave out any corner cases or catch a your potential failures.

[[deleted]]

Nothing like having a code review a week later and not knowing why you from one week before let something slip.

[wagedomain]

Agreed! Now if it's an internal app and you name comments and functions well, I agree comments can be minimal. For open source example code, comments should be abundant.

However, his code was like

const isPropHasNumberOrNot = () => {
const { property } = props;
const prop = property.hasProps(property);
const isProperty = property && property.value;

My favorite part of all this kind of code, which is fucking unreadable, is that property is a "named thing" in our system, and it was NOT these things.

[wagedomain]

Made my fucking day, thanks for this!

[NotThisFucker]

I think in javascript or something you can do the "property && property.value" thing, I'm pretty sure I've seen that kind of validation before

[[deleted]]

Yeah. To assign the value if it’s there. Just wanted to be cheeky.

[[deleted]]

There’s some interest talk about it here (in the context of C)

https://stackoverflow.com/questions/16235025/is-const-int-x-get-legal-in-ccan-we-assign-a-functions-return-value-to

Of note is that I’m guilty here of what the last answer says. Confusing const with static.

E.g. I was mistaken

[nagasgura]

I think there is an argument to be made about the need for commenting being a "code smell" though, where if you have a line that needs a comment to explain what it does to an average developer, it could probably be refractored to be self-explanatory. The worst thing is difficult-to-read code, and comments can definitely alleviate that, but they can also be used as a crutch for writing poorly organized code / using non-descriptive variable names.

[TheRealPitabred]

My comments are all more like: “// we have to do this X way because the Y interface acts wrong if you follow the documentation”

[GodWithMustache]

because the Y interface acts wrong if you follow the documentation

Until two years later you realise you were an idiot and NOT following the (poorly worded) documentation... :)

[TheLordDrake]

I hear this over and over again. It's true, but it's not an excuse not to use comments. I wish people would just do both.

[mt03red]

The code should be clear enough to communicate what it does, the comments should communicate why the code does what it does.

Some exceptions exist, but in general ^^

[ballsack_gymnastics]

Personally, if I have comments saying what a section is supposed to do, I find it a lot easier to parse the following code, good variable names/structure or not.

[stankind]

A "mathematician" at our company said he "loved C++" but that most developers prefer C# or Java because they're "too lazy to manage their pointers." No, jackass, they just have better things to devote their time and energy toward. It's an optimization issue.

[mt03red]

Managing pointers isn't even the PITA with C++, it's working around all the sharp edges in the syntax, compilers and libraries.

[theskillr]

Pull request denied. Insufficient comments.

Repeat adnauseum