Comment your own code.

"But nobody except me will see..."

COMMENT YOUR OWN CODE!!!

Future you will see, and that guy/gal is a completely different person

I’ve gotten to the point I’ll even add PHPDocs to my IF and FOREACH blocks so I don’t have to spend an hour unraveling everything.

Related: Fuck whomever decided endif, endwhile, and endforeach should be the standards in WordPress code. If you have that much trouble remembering what the end brace goes to, that’s what // if (condition) is for...

Because my code wasn't commented on a small personnal project, when I got back on it three months later, I was like "why the hell did I do that"

comment your code, folks.

@gustavonogueira damn you're right!

I've read somewhere that you should make your code so readable that it makes comments obsolete.

I try to apply that as much as possible. I mean what's the use of a comment when the code reads as

if($user->isValidSubscriber()){

return MonthlyEmailEvent::fireTo($user);

}

// This is just some random dummy code, its purpose is just to proof a point.

@ImNotAlfred

You get it.

1. Don't comment your code. Just stop writing shitcode. The code itself should read fluidly like sentences. Stop using so much ifs and for loops, isolate functionality, write more pure methods, stick to DRY & SRP.

2. PHPDoc is completely unnecessary now that PHP has typehints.

3. The only reason to comment your code is if the REAL LIFE scenario it represents is hard to understand for a layperson, like invoicing systems, or hardware interactions in systems programming... sure, sprinkle plently of comments in those cases. Still, do NOT write comments explaining the code itself, but about what the code interacts with and how those systems work.

Let me repeat:

IF YOU NEED COMMENTS EXPLAINING YOUR CODE, YOUR CODE IS SHIT.

So... don't comment about your code, comment about the code your code interracts with? @bittersweet

@Grexius OK let me word it like this:

Comments should only be added when you need the "why", they should never explain what the code does.

What the code does should be readable from the code, and should be a single truth. Comments can diverge from what the code does.

The why could be needed when the real world doesn't abstract as nicely as you'd like. So a comment like:

// Excluding vat tax for first 40 hours of work as freelancer due to labor law section 123

Could be necessary.

But
// Assigning permission to users
Should be clear when you call users.assignPermissions([x, y, z])

In my experience, comments should be kind of a last resort.

The danger of adding "what" comments is that you start reading comments and assume comments to be what the code does. Comments can lie and deceive, comments are incomplete.

Train yourself to write readable code, and read the code when you need to know what it does.

@Grexius As a guideline, I often let our stakeholders and lawyers write comments for the code.

For example, I sit down with a bookkeeper, explain what my code does and how it affects their workflow, and I add their clarifications and requirement specs as comments.

Sparsely, only where absolutely necessary, only in those areas of the code where I feel like "shit this is not about code quality anymore, this is about someone else's expertise in a complex field I know nothing about".

Code should be clear to coders. Comments are reminders about the real world complexities from other experts.

@bittersweet Couldn't have said this better myself. I'm working for a company where we process payments, invoices, credit card details and so on.
This field can be extremely complex at times, and we only use comments to say why we did something, so we know what part of the business it affects and why it does it.

@bittersweet Don't mind me, I agree

But can you say this to the other dev in my company ? I have to comment code

help

Me back in university. Some excuses I used to tell myself included: "I know what I'm doing." And "It's not even that complicated"

Then one day I was trying to teach C# to my brother, and I went over an old program. I didn't know WTF I did, what I was looking at, or where to begin.

After almost half an hour of going through that code, (and impressing myself with my own awesomeness). I could continue my lesson.

I also used that experience as an example of why you should always document your shit.

@gustavonogueira I don't like automated doc systems with blocks which just repeats what the function says -- why would you chalk up the parameters in the comment above the function, I can read what they are in the function definition itself!

They had a purpose, once. Docblocks could provide help to IDEs in providing context and type safety for example.

These days, I'd say switch over to Typescript over JS and PHP7.2 over PHP5.6 -- modern languages should not need to be wrapped in some semantic annotation metalanguage to be usable.

Jupyter is probably the only format where heavy commenting is cool... 🙃

How do I upvote this 5 times ?

@ODXT the ugly truth is that the code you wrote in college is probably shit 😂. If I pull out an old project of mine I did when I was attending college i probably have to look twice too.. but that's exactly the point @bittersweet is trying to make.. if you cant make out what a piece of code does by itself, the author of said code didn't follow the best coding principles.

I know everyone loves to bash on undocumented code. But it's not really the lack of documentation that bothers you, but the inability to understand what that unreadable shitcode does...

Imagen something like this..

// Authenticates the user
$user->authenticate();

I mean... I think you get the point, right ?

Honest to god, even if your commenting the obvious, just do it.
I mean you lose a few seconds while doing it but save yourself/others potentially hours in debugging

Don't describe your code. Write descriptive code. The descriptions should be baked in variable/function names and therefore enforeced at compile time

@ModernShoe True! Both (descriptions and descriptive code) are very important!

@bittersweet you work in a nice place.

But when standards don't exist code is unreadable.

Like a certain 3rd party uses string for a type of action but int for another.

Or that the third time you try something it breaks.

Or that you need to parse something in a certain way.

Sometimes i want to be in the world that these people describe.

"Comment your own code."
"But nobody except me will see it!" "Yes, exactly. Comment your code."

Very refreshing and fresh, thanks
https://ajigsawpuzzles.com