914
you are viewing a single comment's thread
view the rest of the comments
[-] NotAnonymousAtAll@feddit.de 29 points 11 months ago

About comments:

Please please please, do not always write comments. Try to write code that does not need comments whenever possible. Proper variable, class and method names go a long way. If you think a block of code needs a comment, turn it into a method and give it a proper name instead.

Comments should be a last resort for cases where making the code self explanatory is not possible, and those should be rare.

About optimization:

Optimal code is code that fulfills it's purpose without observable issues.

If you try to make something faster without any prior complaints or measurements indicating that it being slow is an actual issue, you are not optimizing, you are just engaging in mental masturbation.

[-] squaresinger@feddit.de 15 points 11 months ago

I strongly disagree with the comments. "The code is the documentation" was a dumb joke about being to lazy to write documentation, not a best practices guideline.

Proper naming is good, but there are a lot of issues with not commenting code. Obviously it's dumb to comment every line, but it's really useful to comment functions/methods, because otherwise you never know if something's a bug or a non-obvious feature. Comments act as a parity check to the code, since they tell you what the dev who wrote the code wanted the code to do.

Also, everone thinks they write good, clean and obvious code. Hardly anyone purpously writes bad, hacky code. Yet if you look at code you wrote a year ago, or code someone else on your team wrote, it's full of non-obvious hacks. That means, people constantly misjudge the obviousnes of their code. Comments should be put on anything that could maybe be non-obvious.

And putting documentation of the code anywhere else than in a comment (e.g. Confluence) is a total waste of time (unless you put a link to the specific page of the documentation in a comment in the code), because documentation that you don't directly see without effort will not be found and not be read.

[-] h_a_r_u_k_i@programming.dev 6 points 11 months ago

"Code is the documentation" is the paradise we all want to be someday. But some people use that as an excuse to not write the documentation explaining why this piece of code exists in the first place. I find it extremely annoying when there is not a single architecture diagram is available and someone tell me to figure it out by reading his/her spaghetti code.

[-] Von_Broheim@programming.dev 2 points 11 months ago

The problem is that code is language and people who write shit code tend to write shit comments, so no value is gained anyway. The sort of person who'd write good comments will most likely write good code where these comments are not needed, and when they intentionally write shit code they'd probably explain why.

So best you can hope for is that both of these people write comments about why they decided to write a comment, and hopefully the person who writes shit code improves over time.

load more comments (5 replies)
load more comments (13 replies)
this post was submitted on 05 Aug 2023
914 points (96.2% liked)

Programmer Humor

18319 readers
771 users here now

Welcome to Programmer Humor!

This is a place where you can post jokes, memes, humor, etc. related to programming!

For sharing awful code theres also Programming Horror.

Rules

founded 1 year ago
MODERATORS