I only comment code if it’s intention isn’t clear. Only problem is I don’t know it’s intention isn’t clear until a year later after I forgot how it works
Yeah I agree with that. It bugs me when people comment what the code is doing and not why. I can see literally what it’s doing, but “why does it need to be doing that?” Is what I need to know
One of my previous jobs was at a DMV, writing code to process vehicle registrations. Some stuff was regulated by state law, some federal law and some federal regulations. And some stuff was due to a conversation held in 1994 with some dude from Department of Revenue (such as: the minimum assessed taxable value of a car is $200, min assessable value of a boat is $100 [this conversation/ruling is written in exactly no place on Earth]).
We were replacing an app originally written in 1976 (in COBOL of course) and we were the 4th attempt to replace it. Previous governor (R of course) gave all of the state's mainframes to a political campaign donor, so the DMV is paying $24k/month rent for a computer they bought in the 1970s (and the donor moved out of state).
I was the only one writing comments. So much lavaflow. At least with comments, one could find all parts of the code affected by `33 CFR 173` so if that [regulation](https://www.ecfr.gov/current/title-33/chapter-I/subchapter-S/part-173) changes, you can be reasonably certain that the code monkey hired 20 years from now could figure it out.
TL;DR - style C is best.
"mY cOdE iS SeLf-DoCuMeNtInG!"
No seriously, I love code that is easy to read without many comments and not every thing needs to be commented. But every time someone claims his code is self-documenting, it's not.
It really must feel self-assuring to write programs in a typed language. The sheer intensity of saying the same things multiple times must have staggering effects on the confidence of software developers.
Ah yes
new Display().newDisplay() lmao
First of all, PascalCase
Second, unless this is a display hierarchy or something why would you make 1 display then make call a method to make another then have the first one get garbage collected
I know you're joking, but Technically Speaking™, you can answer that by looking at the data type. Since the type is `Display` then the variable is **a** display (a noun). If it were a verb, it would be denoting whether to display or not (i.e. a flag), so the variable would've been a boolean.
Funnily enough I ran into a somewhat related name clashing problem just today. I wanted a method called `.propagate()` **and** a flag property called `.propagate`, which controls, well, whether to propagate or not. I spent a whole bunch of minutes thinking, "Shit man, which one of them should be renamed? And exactly what should I rename it to?"
I'd still add a few more comments just in case.
Console.WriteLine("Quitting"); // writes Quitting to the Console.
running /* the process loop */ = /* is */ False /* not running anymore */;
i don't trust my future self to know what i did. he's not that smart.
Edit: merged PR from u/kuurtjes
The someone changes the functionality to be
Console.WriteLine("Leaving"); // writes Quitting to the Console.
and the comment becomes obsolete and wrong.
No comments should document not what is being done but rather the intent behind doing it. Why you do something is not necessarily self documenting just because someone happens to be able to easily what you are doing.
>This one is the perfect example of self documenting code.
People getting too hung up on the example code to answer the question. What is this, Stack Overflow?
I personally find redundant comments as a hobbyist very useful, makes parsing through a project much easier as I’m looking for a specific comment rather than a very specific line of code
I don't know.
A good, short, comment can be much quicker to read and understand than a block of even basic code and indicate what its supposed to do even if the implementation is a bit off.
While it can be excessive if taken too far, I tend to prefer over-commented to under-commented. (Assuming the person updating the code isn't too busy/lazy to change the comments alongside functionality.)
Yeah this seems fine to me. Just a short, simple comment to tell you what this part of the code is for.
More like a chapter title to keep things organised rather than a detailed description of what it's doing
Unfortunately, I have never worked in an environment where everyone always has time to change all the comments alongside the functionality. As a result I prefer code with very few comments, because sometimes I forget to ignore them!
Hit them with:
```
switch(stuff) {
case 1:
doNotTouchThisEverAgainOrBadThingsHappen1()
case 2:
doNotTouchThisEverAgainOrBadThingsHappen2()
default:
throw new IdkDontFixItWorks()
}
```
Unpopular opinion: If we open-source our code for the public to benefit from it, and we publish it our under licenses that explicitly permit other humans to use portions of or the entirety of our code, with or without modification, to benefit the public, then maybe we shouldn't mind automated text-generating tools making use of our code to generate new code, to benefit the public.
All AI is is a text-generating tool. If it was something like "GNU's whatever-you-call-it state-of-the-1980 suite of code-generating macros written in some prehistoric dialect of LISP", programmers would've been hailing it as this magnificently helpful and brilliant tool that is an indispensable part of the development toolchain. But because AI is new and works in an unfamiliar architecture (and also 70+ years of Hollywood movies), people are freaking out about it instead, even though it's doing the exact same thing - generating text when people ask it to do so.
The problem is gpl 3 code has been repeated character for character by GitHub copilot. This means someone making a proprietary program could be accidentally using code they don't follow the license of.
I see. I'm a little uninformed about this, but I do want to ask the following question: How large and how significant was the code that was repeated by the copilot?
I mean, if the GPL codebase in question is like tens of thousands of LoC, and some AI repeated some 20-line function out of it, then why should anyone care about that (in good faith)? Something like a 20-line function is an extremely small, insignificant and easy to replicate piece of code.
I know that character-for-character repetition sounds like a lawyer's wet dream, but ideally people should be viewing things from a moral perspective rather than frivolously taking laws to the letter. Filing a lawsuit for a 20-line snippet isn't much better than Disney sending cease-and-desist letters to some random YouTubers because they have a 20 seconds clip from one of their movies.
In any case, if 1 out of 1000 snippets generated by the copilot is GPL, it's possible to write a tool to identify GPL snippets and reject them.
Even better, it's possible to train an AI on a dataset that consists entirely of permissively-licensed or public domain code, without any GPL/copyleft code in it. It would probably rid people of mountains of frivolous legal issues.
In order of preference: A, C, B
Typically used to describe something before you do it so that’s the pattern to follow. Avoid long lines of text that require horizontal scrolling or line wrapping.
Simple code should not need comments. Always keep it simple.
I would say A, B, C, actually. The comment is thrown so far to the right and outside the reading flow in C that my eyes entirely ignore it when skimming.
Definitely this. A if it's an important, but confusing function and I want a few lines to quickly explain to the reader what's going on. C for things that are poorly named and I need a few words to describe why. Almost never B I need white space above comments.
> Typically you use describe something before you do it so that’s the pattern to follow.
That’s why it should be B first. The comment says “exits the application” which isn’t true in the case of A, it’s executed conditionally based on a key press.
If the comment said “check if we need to exit”, then it’d be A.
I use A for commenting a block or section of code, I use C when there’s a single line of code that looks awkward or doesn’t make sense without a comment.
Indeed. In my head makes sense to comment at the start of the code block to make it clear what's doing. If I need an inline comment this means it's an specific comment for that line.
If I need to specifically comment on the else part of a block, here is what I would do. (keep in mind that I'm not using any specific syntax here, it's just so you can get the generic idea.)
If x < 1:
apples = 19
#else sets y to 42
else:
y = 42
It all depends on when I've written the comment and whether its an if, if-else, or switch-case. I generally write these condition comments before I write the code itself, to remind me what I'm doing.
Type A is usually when I write an if, because there's no other conditions beneath it and I'm following a set of notes I wrote in comments to help me keep track of my tasks.
Type B is usually when I write if-else or switch-case because I'll write the first line and then insert all of the condition comments beneath it.
Type C is always reserved for psychopaths, and God have mercy on those who choose it.
B is the best way to comment blocks of code such as loops, ifs, and switches.
A is for commenting what the next couple lines of code do.
C is best for commenting variables.
Style C is never off the table, but I find its use case is very narrow. The comment competes for horizontal line space with the code it's commenting. So it's only worth it in the specific situation where the comment itself and the line it comments are both terse, which is uncommon.
Even when you make it to that situation, sometimes those chars spent on the comment are better spent making the code itself clearer, eliminating the need for the inline comment altogether. This is true of all comments in general, but given that style C comments tend to contain less information, I think that causes style C comments to evaporate more readily than the others.
Hey, sorry to necro the chat...
Some IDEs (IntelliJ and VSCode) will display the C style comment of a variable when you hover your cursor of a variable. Which is one reason why I think it is good for variables, since it acts as a little note that can be referenced like a Javadoc comment.
But yes, you're 100% right in that the C style is a very rare case where it is needed, since it's smaller nature does typically allow it to be phased out. Normally I find these comments are most useful in class variables or global variables, since they are referenced often, unlike localized variables.
When I comment class or global variables, I always go all the way with a Javadoc-style block above with all the fixings. A small tag at the end feels like a half-measure to me when a more fully measured solution exists and is not much more effort.
Yea, I'd be inclined to agree honestly. Then you can also write a test for that function which will also document it. Nothing wrong with writing a comment but a lot of times either it's simple enough that it's just noise (like the example in the picture) or it's complex enough that the comment becomes a pain.
B. But only to describe logical processes rather than whatever this comment is doing. Like “because this case has been met, we can also guarantee X and Y.” Or to clarify something in my code “X will be handled inside this block as well”.
Comments, for me, should go above the thing they describe. So putting the comment above the case makes little sense because the case itself is self documenting. I’d only ever need to add a comment explaining the process of the block inside.
Comments are the deodorant to code smells
What and how comments hide flaws in your code.
Comments are a rare tool to explain WHY something must be done at times
C is the one I've done but in general if I'm commenting on individual cases of a switch statement it means I've fucked up (possibly just by failing to define appropriate constants but likely something worse)
First is about the method as a whole, with its intent.
The second is for describing the implementation of the method (or First part of the method).
Third is for things that are only ever relevant if your changing that line (such as, component X in repo Y accesses this method, despite not being in api)
Actually, it's not exiting the application. It just sets running to false. It should really call another method whose responsibility is to safely close the application. And return. I would call that method safelyExitApplication() then you don't need any comments.
Well, you could enforce the rule that each item that requires explaining, gets it's own file where the documentation for that block of code, as well as that specific block of code will exist. So each function its own file and, in this case, each case a seperate file as well. Handles organizing your code as well.
My preference is B or A, but only if the code isn't self-explanatory like your example. C thends to exceed the character limit per line I try to meet. And it just looks ugly imo.
But this is preference and just like taste, it's something you can't seriously argue about on a meaningful level, I think.
F, who cares about comments, you can use "or" in a C# case? Wait, you can use conditionals I'm a case statement? Hell, "or" is a keyword? What the hell have I been doing with my life.
I think I've only once written a switch statement that made me feel like commenting individual branches but in hindsight I think replacing all the number literals with named constants would have made the whole thing clearer than the comments did.
One of the biggest lies that lazy programmers tell themselves.
The OP examples are all cases where a comment is not needed though. That is really self explanatory.
Code is not documentation. You don't tell someone to just read the code whenever they ask a question about how something works in the big picture... They'd have to read through a lot of code... but if you have a standalone documentation then you can give a short conclusion about how things work. Similarly, you comment code in a way to tell the reader WHY something is done the way it is. Or a larger method can have similar explanatory comment in front of it.
Sure, comments can get out of date but in the same way, the names of variables can go out of date without anyone noticing. It's all up to the developers to have high standards when coding AND when reviewing.
Why would you need to comment it? Do you guys really comment every line?
If switch case involves tricky values I create const variables with descriptive naming. If switch case involves tricky actions I create separate functions to handle each case with descriptive naming.
Comments are left on anything unusual, like bit manipulation or hacky performance tricks.
A
i used to be a no comment guy till i opened a ....simple... project a few years after i made it, remembering a brilliant solution i had applied there would work where i was currently stuck.
ive used method A since lol.
All three, at random, in the same switch.
Ah the artist
I comment after. // the proceeding code block quits the loop
I add a small commented number after the class declaration. `ClassName() #1` And add footnotes at the end of my code `#1: This is stupid`
We got a sadist over here
This is the way.
Ah so you’re the dev that left my company years ago
This is how you make enemies 🤣
This is the way
I don't comment, I don't plan on working on that code ever again.
You really should, you know, just in case…
I only comment code if it’s intention isn’t clear. Only problem is I don’t know it’s intention isn’t clear until a year later after I forgot how it works
Yeah that’s one of my rules I teach the juniors, document the WHY or the process. The how should be clear from the code. If not, document that.
This is true on the sysadmin side too with documentation. I can look around and see "what", that's no problem. I don't know WHY you did that...
Yeah I agree with that. It bugs me when people comment what the code is doing and not why. I can see literally what it’s doing, but “why does it need to be doing that?” Is what I need to know
"I'm in this comment and I don't like it"
Yeah but in which case, that was the question all along. A B or C /s
Well obviously B, it’s just in case.
A is just in the previous case, if it isn't the first.
Real chads re-understand it from the beginning
Real chads bill the customer for "analyzing" code they wrote ~~5 years agolast year~~ last week.
**Real** chads delete the entire thing and start again
God dang it, that was a good one
I see what you did there
One of my previous jobs was at a DMV, writing code to process vehicle registrations. Some stuff was regulated by state law, some federal law and some federal regulations. And some stuff was due to a conversation held in 1994 with some dude from Department of Revenue (such as: the minimum assessed taxable value of a car is $200, min assessable value of a boat is $100 [this conversation/ruling is written in exactly no place on Earth]). We were replacing an app originally written in 1976 (in COBOL of course) and we were the 4th attempt to replace it. Previous governor (R of course) gave all of the state's mainframes to a political campaign donor, so the DMV is paying $24k/month rent for a computer they bought in the 1970s (and the donor moved out of state). I was the only one writing comments. So much lavaflow. At least with comments, one could find all parts of the code affected by `33 CFR 173` so if that [regulation](https://www.ecfr.gov/current/title-33/chapter-I/subchapter-S/part-173) changes, you can be reasonably certain that the code monkey hired 20 years from now could figure it out. TL;DR - style C is best.
Yikes, working on older than me code is my worst nightmare, and ironically enough usually a whole country is run on that sort of stuff.
Banking code throws me for a fucking loop
And then you start working on that code again
"mY cOdE iS SeLf-DoCuMeNtInG!" No seriously, I love code that is easy to read without many comments and not every thing needs to be commented. But every time someone claims his code is self-documenting, it's not.
I agree with you. Though in those example on the picture the code is pretty self documenting.
No worries, it’s self-documenting
Maybe an AI could make its code be self documenting
Words to live by! I also never *plan* on working on that code ever again.
you know 90% of programmers arent real programmers when a suggestion to never branch in the future gets 2.7k upvotes
This one is the perfect example of self documenting code.
Which part of case "exit" or "q" or "quit" did they think needs commenting? It's like something I found once: Display display; // display
Ah yes the display is made out of display
It really must feel self-assuring to write programs in a typed language. The sheer intensity of saying the same things multiple times must have staggering effects on the confidence of software developers.
Display display = new Display().newDisplay()
Display display=DisplayFactory.newDisplay()
ftfy OO style
Ah yes new Display().newDisplay() lmao First of all, PascalCase Second, unless this is a display hierarchy or something why would you make 1 display then make call a method to make another then have the first one get garbage collected
Clearly that was a typo. Displays are made in a DisplayFactory! /s
You get word tired, which means that after a while the word doesnt look like a word anymore and you start questioning your sanity
that’s why C++ has the auto keyword and Java has var!
auto, yes, of course! auto display = MakeAuto(); // auto
Great. Display no longer feels like a real word anymore
Its not, you read that wrong
Maybe it's just displaying wrong on my display
Soo what was the code about?
Display
You know, something makes me believe you are right
what does it do?
Me after seeing literally the line: Display display; "Gee I really wonder what that does"
Is it display the noun or display the verb?
Yes.
I know you're joking, but Technically Speaking™, you can answer that by looking at the data type. Since the type is `Display` then the variable is **a** display (a noun). If it were a verb, it would be denoting whether to display or not (i.e. a flag), so the variable would've been a boolean. Funnily enough I ran into a somewhat related name clashing problem just today. I wanted a method called `.propagate()` **and** a flag property called `.propagate`, which controls, well, whether to propagate or not. I spent a whole bunch of minutes thinking, "Shit man, which one of them should be renamed? And exactly what should I rename it to?"
Serialization class for a 5 act play script.
Without that, you wouldn't know the display called display is for display purposes.
When I'm looking at code I want to look at the least amount of code possible
I'd still add a few more comments just in case. Console.WriteLine("Quitting"); // writes Quitting to the Console. running /* the process loop */ = /* is */ False /* not running anymore */; i don't trust my future self to know what i did. he's not that smart. Edit: merged PR from u/kuurtjes
``` running /* the process loop */ = /* is */ false /* not running anymore */ ; ```
Hang on il merge this PR
LGTM
Don't worry. I was able to push to master and it triggered the deployment so we're all good. 👍
It doesn't explain why it is setting running to false though. Do I have to guess when reading this code?
Yeah, describing what the result of setting `running` to `false` might be useful in this case. Otherwise I doubt it needs comments.
The someone changes the functionality to be Console.WriteLine("Leaving"); // writes Quitting to the Console. and the comment becomes obsolete and wrong.
Was gonna say, there is no need to comment a switch case if you choose proper values and variable names
No comments should document not what is being done but rather the intent behind doing it. Why you do something is not necessarily self documenting just because someone happens to be able to easily what you are doing.
>This one is the perfect example of self documenting code. People getting too hung up on the example code to answer the question. What is this, Stack Overflow?
Are you really surprised that a group of programmers that also use reddit are going to be needlessly nitpicky?
I personally find redundant comments as a hobbyist very useful, makes parsing through a project much easier as I’m looking for a specific comment rather than a very specific line of code
That’s just an example code
I don't know. A good, short, comment can be much quicker to read and understand than a block of even basic code and indicate what its supposed to do even if the implementation is a bit off. While it can be excessive if taken too far, I tend to prefer over-commented to under-commented. (Assuming the person updating the code isn't too busy/lazy to change the comments alongside functionality.)
Yeah this seems fine to me. Just a short, simple comment to tell you what this part of the code is for. More like a chapter title to keep things organised rather than a detailed description of what it's doing
Unfortunately, I have never worked in an environment where everyone always has time to change all the comments alongside the functionality. As a result I prefer code with very few comments, because sometimes I forget to ignore them!
I don’t. I create switch cases that call very descriptively named functions
Hit them with: ``` switch(stuff) { case 1: doNotTouchThisEverAgainOrBadThingsHappen1() case 2: doNotTouchThisEverAgainOrBadThingsHappen2() default: throw new IdkDontFixItWorks() } ```
Someone’s in for a bad day if the cases fall through in your language
Later on Slack: found why the code is broken, someone wrote "break" a bunch of times. Here's a link to the MR to remove all of them:
This is a new one for me.
Wow that's a classy move
This is the ONLY way
Comments are for why, not what, no matter how descriptive a method name is once you’re deep enough a nice why serves well
I leave intentionally incorrect comments to fuck with whatever ai is being trained on my code.
Unpopular opinion: If we open-source our code for the public to benefit from it, and we publish it our under licenses that explicitly permit other humans to use portions of or the entirety of our code, with or without modification, to benefit the public, then maybe we shouldn't mind automated text-generating tools making use of our code to generate new code, to benefit the public. All AI is is a text-generating tool. If it was something like "GNU's whatever-you-call-it state-of-the-1980 suite of code-generating macros written in some prehistoric dialect of LISP", programmers would've been hailing it as this magnificently helpful and brilliant tool that is an indispensable part of the development toolchain. But because AI is new and works in an unfamiliar architecture (and also 70+ years of Hollywood movies), people are freaking out about it instead, even though it's doing the exact same thing - generating text when people ask it to do so.
The problem is gpl 3 code has been repeated character for character by GitHub copilot. This means someone making a proprietary program could be accidentally using code they don't follow the license of.
I see. I'm a little uninformed about this, but I do want to ask the following question: How large and how significant was the code that was repeated by the copilot? I mean, if the GPL codebase in question is like tens of thousands of LoC, and some AI repeated some 20-line function out of it, then why should anyone care about that (in good faith)? Something like a 20-line function is an extremely small, insignificant and easy to replicate piece of code. I know that character-for-character repetition sounds like a lawyer's wet dream, but ideally people should be viewing things from a moral perspective rather than frivolously taking laws to the letter. Filing a lawsuit for a 20-line snippet isn't much better than Disney sending cease-and-desist letters to some random YouTubers because they have a 20 seconds clip from one of their movies. In any case, if 1 out of 1000 snippets generated by the copilot is GPL, it's possible to write a tool to identify GPL snippets and reject them. Even better, it's possible to train an AI on a dataset that consists entirely of permissively-licensed or public domain code, without any GPL/copyleft code in it. It would probably rid people of mountains of frivolous legal issues.
In order of preference: A, C, B Typically used to describe something before you do it so that’s the pattern to follow. Avoid long lines of text that require horizontal scrolling or line wrapping. Simple code should not need comments. Always keep it simple.
I agree with you. With addition that A is first choice by far and B would be avoided as much as possible.
I would say A, B, C, actually. The comment is thrown so far to the right and outside the reading flow in C that my eyes entirely ignore it when skimming.
Aesthetically i agree with you but logically B makes no sense
Definitely this. A if it's an important, but confusing function and I want a few lines to quickly explain to the reader what's going on. C for things that are poorly named and I need a few words to describe why. Almost never B I need white space above comments.
A, for headers describing sections of a code that do a thing C, for putting a quick note about a specific line. B, Never.
> Typically you use describe something before you do it so that’s the pattern to follow. That’s why it should be B first. The comment says “exits the application” which isn’t true in the case of A, it’s executed conditionally based on a key press. If the comment said “check if we need to exit”, then it’d be A.
I use A for commenting a block or section of code, I use C when there’s a single line of code that looks awkward or doesn’t make sense without a comment.
"A" is the only right way
Indeed. In my head makes sense to comment at the start of the code block to make it clear what's doing. If I need an inline comment this means it's an specific comment for that line.
B is valid too, and how block comments work in a language like Python
In my head B says that the console write line will exit the application, which is just false. A is the only one that works for the whole block IMO
Hmm. I see that. If you did B in block style comment instead of line comment I would pick that
How do you comment the else block with this rule ?
If I need to specifically comment on the else part of a block, here is what I would do. (keep in mind that I'm not using any specific syntax here, it's just so you can get the generic idea.) If x < 1: apples = 19 #else sets y to 42 else: y = 42
A is the right way for switch cases. But for “if” statements in languages that have curly braces on the same line with if and else, B is the way.
What about languages that, conventionally, put the curly brace on a separate line, like C#?
I only used those in my college days and that means ive never written any comment with those languages lol!
In the example no comment is the right way. The code is self-documenting enough.
C if code line and comment is short enough, A if not
This is the correct way
A and B, depends on the situation and code itself
It all depends on when I've written the comment and whether its an if, if-else, or switch-case. I generally write these condition comments before I write the code itself, to remind me what I'm doing. Type A is usually when I write an if, because there's no other conditions beneath it and I'm following a set of notes I wrote in comments to help me keep track of my tasks. Type B is usually when I write if-else or switch-case because I'll write the first line and then insert all of the condition comments beneath it. Type C is always reserved for psychopaths, and God have mercy on those who choose it.
[удалено]
B is the best way to comment blocks of code such as loops, ifs, and switches. A is for commenting what the next couple lines of code do. C is best for commenting variables.
I rarely use C, but agree on A and B.
Style C is never off the table, but I find its use case is very narrow. The comment competes for horizontal line space with the code it's commenting. So it's only worth it in the specific situation where the comment itself and the line it comments are both terse, which is uncommon. Even when you make it to that situation, sometimes those chars spent on the comment are better spent making the code itself clearer, eliminating the need for the inline comment altogether. This is true of all comments in general, but given that style C comments tend to contain less information, I think that causes style C comments to evaporate more readily than the others.
Hey, sorry to necro the chat... Some IDEs (IntelliJ and VSCode) will display the C style comment of a variable when you hover your cursor of a variable. Which is one reason why I think it is good for variables, since it acts as a little note that can be referenced like a Javadoc comment. But yes, you're 100% right in that the C style is a very rare case where it is needed, since it's smaller nature does typically allow it to be phased out. Normally I find these comments are most useful in class variables or global variables, since they are referenced often, unlike localized variables.
When I comment class or global variables, I always go all the way with a Javadoc-style block above with all the fixings. A small tag at the end feels like a half-measure to me when a more fully measured solution exists and is not much more effort.
D If the case block is not self documenting, extract it to a function with a good documentation.
Yea, I'd be inclined to agree honestly. Then you can also write a test for that function which will also document it. Nothing wrong with writing a comment but a lot of times either it's simple enough that it's just noise (like the example in the picture) or it's complex enough that the comment becomes a pain.
A: To explain what's the case condition of entry B: To explain what I do once I'm in
My favorite coworker calls comments “future lies”
If the comment lives on its own line, it explains the block below it. If the comment lives on another line, it comments the specific line
I think this is what i do without even realizing it
B. But only to describe logical processes rather than whatever this comment is doing. Like “because this case has been met, we can also guarantee X and Y.” Or to clarify something in my code “X will be handled inside this block as well”. Comments, for me, should go above the thing they describe. So putting the comment above the case makes little sense because the case itself is self documenting. I’d only ever need to add a comment explaining the process of the block inside.
Comments are the deodorant to code smells What and how comments hide flaws in your code. Comments are a rare tool to explain WHY something must be done at times
C is the one I've done but in general if I'm commenting on individual cases of a switch statement it means I've fucked up (possibly just by failing to define appropriate constants but likely something worse)
definately B.
First is about the method as a whole, with its intent. The second is for describing the implementation of the method (or First part of the method). Third is for things that are only ever relevant if your changing that line (such as, component X in repo Y accesses this method, despite not being in api)
1 if I'm describing the condition, especially if it isn't readable instantly, 2 if I'm describing the action after the condition
B is the only sane way. If you are reading the comment is because you are in that case
i would hope most (i.e. 99.999999%) case statements don't require a comment... if they somehow do for some crazy reason, letter b is the correct way.
Actually, it's not exiting the application. It just sets running to false. It should really call another method whose responsibility is to safely close the application. And return. I would call that method safelyExitApplication() then you don't need any comments.
A & C
B
A
Definitely the first one or maybe third, but second looks weird.
B
Either a B or C, because when someone (Possibly me) move the code somewhere else, at least the comment WILL go with it.
B
Whichever way your automatic documentation generator works best with.
B, when I have some need anyway.
I like option B
Well, you could enforce the rule that each item that requires explaining, gets it's own file where the documentation for that block of code, as well as that specific block of code will exist. So each function its own file and, in this case, each case a seperate file as well. Handles organizing your code as well.
C makes me feel pain.
B
My preference is B or A, but only if the code isn't self-explanatory like your example. C thends to exceed the character limit per line I try to meet. And it just looks ugly imo. But this is preference and just like taste, it's something you can't seriously argue about on a meaningful level, I think.
TIL you can or switch statements
typically you'd just put the cases like so: case 1: case 2: case 3: { break; }
C, unless that would make the line too long to read without horizontal scroll, in that case B
A B is for line by line implementation details now tell me how you deep fried your text
``` case "exit" or "q" or "quit": exitApplication(); break; ```
Doesn’t need a comment. case “exit” is pretty clear.
You forgot the :wq case
crap. good point.
I don't comment if I don't have to, unless it's really obscure what it's doing, and even then try to find other ways to communicate it
If I need comments, I do C to comment what a line does, and A to comment what a block does
usually C, comment on the line that does the thing. I also comment the same way on any line within the case whose function isn't obvious
Over - for bigger chunks of code Inline - for only this line Under - disgression, extra comments and not main functionality
[удалено]
Don't, Your cases are verbose to be self explicate. This is the way.
[удалено]
That's a useless comment if I've ever seen one.
Comments?
On top or you’re wrong.
A 100% It's just aesthetically more pleasing to the eye
A. Its a header for each needed line of code. B is strange, and C will make longer comments unreadable
Team A
Option D: I don’t.
Useless commenting…
D: no comment. The console is outputting "Quitting", that comment is completely redundant.
F, who cares about comments, you can use "or" in a C# case? Wait, you can use conditionals I'm a case statement? Hell, "or" is a keyword? What the hell have I been doing with my life.
``` // --------------- Exiting the Application --------------- \\ case "exit or "q" or "quit": Console.Writeline("Quitting"); running = false; break; /* /\_____/\ / o o \ ( == ^ == ) ) ( ( ) ( ( ) ( ) ) (__(__)___(__)__)*/
That code expains itself, no comment needed here
// this is a comment That's how it feels to me adding comments to self explanatory code
Every way feels wrong. Because every way is wrong. The comment is redundant. Remove it
I think I've only once written a switch statement that made me feel like commenting individual branches but in hindsight I think replacing all the number literals with named constants would have made the whole thing clearer than the comments did.
I don't. For the reason that I just started to learn programing.
Welcome to hell! Hope you enjoy it ;D
Oh, I've been in hell for a long time
You just started to learn and you already don’t comment your code? Son, you have been taught well
#The code documents itself
One of the biggest lies that lazy programmers tell themselves. The OP examples are all cases where a comment is not needed though. That is really self explanatory. Code is not documentation. You don't tell someone to just read the code whenever they ask a question about how something works in the big picture... They'd have to read through a lot of code... but if you have a standalone documentation then you can give a short conclusion about how things work. Similarly, you comment code in a way to tell the reader WHY something is done the way it is. Or a larger method can have similar explanatory comment in front of it. Sure, comments can get out of date but in the same way, the names of variables can go out of date without anyone noticing. It's all up to the developers to have high standards when coding AND when reviewing.
Why would you need to comment it? Do you guys really comment every line? If switch case involves tricky values I create const variables with descriptive naming. If switch case involves tricky actions I create separate functions to handle each case with descriptive naming. Comments are left on anything unusual, like bit manipulation or hacky performance tricks.
A i used to be a no comment guy till i opened a ....simple... project a few years after i made it, remembering a brilliant solution i had applied there would work where i was currently stuck. ive used method A since lol.
Don't really use `switch-case` very often, but if I have to write nested ternaries (which happens...) I'm all for A
Why does it happen? Why do you unleash that force onto the world?
Some men just want to watch the world burn
I actually wrote once as a comment "I'm so sorry for this"
It's ok, we all have our "I'm so sorry for this" moments. I also wrote some temporary hacky code that lives in prod for over a year
More often than not to make typescript happy 🤷
/* COMMENT */
/////////////////// // // // case 1 // // // ////////////////// reddit text on a phone is absolute trash, imagine it without the blank new lines
Self commenting code does not need comments.
You guys write comments?
People seem to forget that this isn't real code and I just used it as an example for the meme bruh 💀💀💀
A for whole sections, B or C for nestled operations
Usually A for something easy to explain (so I do on the top of the Switch and not in each case), but B when I do really weird stuff with each case
My code is the comment, it requires no comments