How programmers comment their code

It's so bad it's almost artistic

I love it

Yup, my first thought as well. While those days are thankfully over, those braindead BIOS "help" messages remain etched into my mind forever.

Love having to enable "support for sleep state 5" to turn off USB power when the PC is off

That's basically what comments are most useful for. When you're doing something that's not obvious, and want to make sure the "why" doesn't get lost to time.

The best comments are "why" comments, the runner up is "how" comments if high-level enough, and maybe just don't write "what" comments at all because everyone reading your code knows how to read code.

this seems like a great idea as it provides proof in writing just in case the stakeholder complains later on about the thing you implemented at their request

That’s actually the perfect comment, because if anyone ever comes back to fuck with you about it, it’s explained right there. Then you turn it right back around on management and watch them run around like chickens with their heads cut off.

I was porting our old code from PHP to Go at a previous company. I laughed as I copied my then-six-year-old comment "I'm promised by xxxxx that this is a temporary measure <link to slack convo>".

The lack of a return type declaration makes this sooo good.

This being a double physically hurts

Makes sense, people looking for int would find a double

Reminds me of a job I had where c# summaries were mandatory and people used a documentation generator just like that.

/// Ages the Category. public int AgeCategory (...)

Have reviewed 16 year old code for a very well known company in the last week with this exact comment peppered throughout, alongside delightfully helpful comments like:

// do not delete or change this it just works

// TODO temporary fix added 12/09/11 to fix incident must be removed ASAP

// CAUTION this returns false here instead of true like it normally does, not sure why

// if true then matched to valid account not is true

The allowable exception is when the what is a what the fuck, as in you had to use a hack so horrible that it requires an apology comment

Inline comments yes.

Function/Class/Module doc comments should absolutely explain "what".

Unless you're working with people who are too smart, then sometimes the code only explains the how. Why did the log processor have thousands of lines about Hilbert Curves? I never could figure it out even after talking with the person that wrote it.

Document intentions and decisions, not code.

Code should always by itself document the "how" of the code, otherwise the code most likely isn't good enough. Something the code can never do is explain the "why" of the code, something that a lot of programmers skip. If you ever find yourself explaining the "how" in the comments, maybe run through the code once more and see if something can be simplified or variables can get more descriptive names.

For me, that's what was originally meant with self-documenting code. A shame lazy programmers hijacked the term in order to avoid writing any documentation.

Comment should describe "why?", not "how?", or "what?", and only when the "why?" is not intuitive.

The problem with comments arise when you update the code but not the comments. This leads to incorrect comments, which might do more harm than no comments at all.

E.g. Good comment: "This workaround is due to a bug in xyz"

Bad comment: "Set variable x to value y"

Note: this only concerns code comments, docstrings are still a good idea, as long as they are maintained

Code is the what. Comments are the why.

Few things worse than an out of date comment.

In my opinion, it strongly depends on what you're coding.

Low-level code where you need to initialize array indices to represent certain flags? Absolutely comment the living shit out of that. → See response.
High-level code where you're just plumbing different libraries? Hell no, the code is just as easily readable as a comment.

I do also think that, no matter where you lie in this spectrum, there is always merit to improving code to reduce the need for documentation:

• Rather than typing out the specification, write a unit/integration test.
• Rather than describing that a function should only be called in a certain way, make it impossible to do it wrongly by modelling this in your type system.
• Rather than adding a comment to describe what a block of code does, pull it out into a separate function.
• Rather than explaining how a snippet of code works, try to simplify it, so this becomes obvious.

The thing with documentation is that it merely makes it easier to learn about complexity, whereas a code improvement may eliminate this complexity or the need to know about it, because the compiler/test will remember.

This does not mean you should avoid comments like they're actively bad. As many others said, particularly the "why" is not expressable in code. Sometimes, it is also genuinely not possible to clean up a snippet of code enough that it becomes digestable.
But it is still a good idea, when you feel the need to leave a comment that explains something else than the "why", to consider for a moment, if there's not some code improvement you should be doing instead.

Code is not self documenting when decision trees are created based on some methodology that's not extremely obvious

Have you ever worked in a place where every function/field needed a comment? Most of those comments end up being "This is the <variable name>, or this does <method name>". Beyond, being useless, those comments are counter productive. The amount of screen space they take up (even if greyed out by the IDE) significantly hurts legability.

Good code is self documenting as in you don't need to describe what it is doing and it is clear to read. Whoever says that and isn't just repeating what they heard understands that whenever you are doing something not explicit in the code it should be on a comment.

Workarounds and explaining you need to use this structure instead of another for some reason are clear examples, but business hints are another useful comment. Or sectioning the process (though I prefer descriptive private functions or pragma regions for that).

It also addresses the hint that the code should be readable because you're not going to have comments to explain spaghetti. Just a hint, doesn't prevent it. Others also said it, comments are easier to get outdated as you don't have the compiler to assist. And outdated comments lead to confusion.

Its definitely a balance. Good code shouldn't need much commenting, but sometimes you have to do something for a reason that isn't immediately obvious and that's when comments are most useful. If you're just explaining what a snippet does instead of why you're doing it that way, there's probably more work to be done.

What they mean is that the variable names and function names are documentation.

For example changing "for( i in getList() )" to "for( patient in getTodaysAppointments() )" is giving the reader more information that might negate the need for a comment.

I absolutely agree, and I too hate this stupid idea of "good code documenting itself" and "comments being unnecessary".
I have a theory where this comes from. It was probably some manager, who has never written a single line of code, who thought that comments were a waste of time, and employees should instead focus on writing code. By telling them that "good code documents itself", they could also just put the blame on their employees.
"Either you don't need comments or your code sucks because it's not self-documenting"
Managers are dumb, and they will never realize that spending a bit of time on writing useful comments may later actually save countless hours, when the project is taken over by a different team, or the people who initially created it, don't work at the company anymore.

I actually agree that "good enough" code can be self-documenting, but it isn't always enough to achieve my goal which is to make the code understandable to my audience with minimal effort. With that goal in mind, I write my code as I would write a technical document. Consider the audience, linear prose, logical order, carefully selected words, things like that... In general, I treat comments as a sort of footnote, to provide additional context where helpful.

There are limits to self-documenting code, and interfaces are a good example. With interfaces, I use comments liberally because so many of the important details about the implementation are not obvious from the code: exactly how the implementation should behave, expected inputs and outputs under different scenarios, assumptions, semantic meaning, etc. Without this information, an implementation cannot be tested or verified.

What a function does should be self evident. Why it does it might not be.

I follow these simple rules and encourage my colleagues to do so

1. If I'm just shuffling jsons, then yes, the code should be self documented. If it's not, the code should be rewritten.

2. If I implement some complex logic or algorithm, then the documentation should be written both to tests and in the code. Tests should be as dull as possible.

3. If I write multithreading, the start, interruption, end, and shared variables should be clearly indicated by all means that I have: comment, documentation, code clearness. Tests should be repeated and waits should not be over 50ms.

I have worked on larger older projects. The more comments you have, the larger the chance that code and comment diverge. Often, code is being changed/adapted/fixed, but the comments are not. If you read the comments then, your understanding of what the code does or should do gets wrong, leading you on a wrong path. This is why I prefer to have rather less comments. Most of the code is self a explanatory, if you properly name your variables, functions and whatever else you are working with.

One example for self documenting code is typing. If you use a language which enforces (or at least allows, as in Python 3.8+) strong typing and you use types pro actively, this is better than documentation, because it can be read and worked with by the compiler or interpreter. In contrast to documenting types, the compiler (or interpreter) will enforce that code meaning and type specification will not diverge. This includes explicitly marking parameters/arguments and return types as optional if they are.

I think no reasonable software developer should work without enforced type safety unless working with pure assembler languages. Any (higher) language which does not allow enforcing strong typing is terrible.

Lol leave. That is so many levels of braindead.

I would smash everything into a handful of overly-complicated lines.

// this line increments the value of i by 1

i++;

I feel like I am going to have to do the same thing in the end, to get my hand-over accepted.
Should I just copy the line of code and make a comment next to it with:

// It does <paste line of code>

CC BY-NC-SA 4.0

Well, fku that array indeed.

Good code is self-explanatory. You should only comment your code if it does something unexpectedly complicated.

The code shows what is being done. The comments should explain the why.

Hard disagree. It's a lot easier and faster to understand a function that is prefaced with a small line of text explaining what it does rather than trying to figure it out yourself.

It's not about whether you can understand the code or not, it's about efficiency and clarity.

Regardless, comments do speed up understanding.

This is true, but it’s easier and faster to parse plain English and so if I don’t adequately comment my code the first time. I will be commenting it when I have to return to it for whatever reason. Honestly the second round of commenting is more verbose and clearer than the function x does y style of comments I tend to make when coding the first time

Asinine business logic can still make some things very hard to read and digest no matter how well-planned and well-written it is (particularly if it is rushed by the business meaning that engineers don't have time to do it well). As such, there are places where code can't/won't be self-documenting to a useful degree.

answer: the answer

Reply about comment about image

Both jokes can be true 😅

The words of the machine are sacred, Only the impure need explanation

It explains what it does, it does not confirm that it is what was intended.

"What does this section of code do?"

Run it and find out, coward.

Code should absolutely speak for itself. But the occasional comment is still good to explain the 'why' of the code when the why isn't very obvious, often due to a niche requirement. Also any time you have to break out a hack, that needs comments up the ass, what was the bug, what URL did you find the fix at, why does this hack work, etc etc. It's very satisfying to go back and remove those hacks after they are no longer needed, often because the underlying technology fixed the bug that had to be hacked around.

This is the truth. In my experience, the people who often writes comments are also writing the most incomprehensible code.

Comments are frequently getting outdated as well, so they’re not in great help understanding the code either.

visiblen't

I don't know. Anyway, DankPods is awesome, there's a great Lemmy community dedicated to his channel: [email protected]

Looks like it's from this old reddit post from 6 years ago: https://old.reddit.com/r/ProgrammerHumor/comments/8sviu4/code_comments_be_like/

You must be fun to work with.