next »

[DireLogomachist]

My go to rule has always been that you should be able to understand what the code is doing in less than 15 seconds.

Yup. And this is one case where comments can actually hurt code readability. Having explanatory comments peppered throughout your code can break your understanding as you pause to read them. Docstrings are great, constant in-line comments throughout functions aren't.

[Ordnas]

My go to rule has always been that you should be able to understand what the code is doing in less than 15 seconds.

Yup. And this is one case where comments can actually hurt code readability. Having explanatory comments peppered throughout your code can break your understanding as you pause to read them. Docstrings are great, constant in-line comments throughout functions aren't.

I just write a comment at the top of the function explaining what it does, and the variable names have descripting name of what they are doing, helping the readability. I would just add a single-line comment inside a function if I do something "strange" that it is not intuitive.

[popawheelie]

My go to rule has always been that you should be able to understand what the code is doing in less than 15 seconds.

Yup. And this is one case where comments can actually hurt code readability. Having explanatory comments peppered throughout your code can break your understanding as you pause to read them. Docstrings are great, constant in-line comments throughout functions aren't.

I just write a comment at the top of the function explaining what it does, and the variable names have descripting name of what they are doing, helping the readability. I would just add a single-line comment inside a function if I do something "strange" that it is not intuitive.

I'm pretty bad about placing comments at top of functions, but always use long descriptive variable names, the exception being counters (IE i,j,k etc)

Some other practices I have to help with readability (and by no means are these considered standard, and maybe even go against convention)

1) Class Names always start with upper case letters and in my case have a 'Bx' prefix. This allows me to easily differentiate from other third party classes: BxMyClass

2) Class variables are always at least two words, with the first lower case: myClassVariable

3) Local variables are all lower case, and split up with underscores: my_local_variable

4) Constants are all uppercase: MY_CONSTANT

[qMopey]

Don't really like comments in code. Typically they decay over time, meaning they are just a liability. I like to treat comments the same as code; use them sparingly as when justified.

[JWki]

Don't really like comments in code. Typically they decay over time, meaning they are just a liability. I like to treat comments the same as code; use them sparingly as when justified.

Yeah I went from comment everything to comment only when really necessary and otherwise try to write understandable code. Situations where magic constants appear for example justify a short note on the reasoning for the specific value.

[ProgramGamer]

I have to write comments at the end of every line of code for every assignment I turn in for two of my college courses.

[DireLogomachist]

I have to write comments at the end of every line of code for every assignment I turn in for two of my college courses.

good god

[oahda]

makes sense in a school context tho, just like notes that show how you arrived at your answer for a maths test are required

[ProgramGamer]

Yeah, I'm not knocking the learning benefit of them, it's just that it's tedious as all hell trying to maintain the horizontal alignment if I have to change something, which means I usually just do that last. I do wish there was some kind of tool for automatically aligning comments and preventing line returns from changing the line on which the comments sit. It would make comments way easier to maintain.

Maybe I could make a VS extension for that? Hm...

[oahda]

i just put the comments on a line above the line of code instead of after it on the same line (with certain exceptions)

[InfiniteStateMachine]

Yeah, I'm not knocking the learning benefit of them, it's just that it's tedious as all hell trying to maintain the horizontal alignment if I have to change something, which means I usually just do that last. I do wish there was some kind of tool for automatically aligning comments and preventing line returns from changing the line on which the comments sit. It would make comments way easier to maintain.

Maybe I could make a VS extension for that? Hm...

Maybe I'm misunderstanding your issue but that should work fine if you select the code region and then go ctrl-k, ctrl-f. Or if you want to format the whole file ctrl-a,ctrl-k,ctrl-f

[JWki]

Yeah, I'm not knocking the learning benefit of them, it's just that it's tedious as all hell trying to maintain the horizontal alignment if I have to change something, which means I usually just do that last. I do wish there was some kind of tool for automatically aligning comments and preventing line returns from changing the line on which the comments sit. It would make comments way easier to maintain.

Maybe I could make a VS extension for that? Hm...

I'm going to go ahead and knock the learning benefit then. Seems utterly useless and like a waste of time to me tbh. Like this I imagine would blow up the time needed to finish an assignment immensely, while failing to teach how to write self documenting code. There's benefit in having to write some amount of comments to demonstrate understanding but I'm pretty sure one per line is just bullshit.

[oahda]

{ // open the scope
...
} // end the scope

[Ordnas]

I do not like very much Google Comment style:
https://google.github.io/styleguide/cppguide.html#Comment_Style

I would use /* */ instead of a double backslash every line, and commenting how the function should be use forces you to have a massive block of comment, when I can just look in the code how that function is being used.

[Crimsontide]

I do not like very much Google Comment style:
https://google.github.io/styleguide/cppguide.html#Comment_Style

I would use /* */ instead of a double backslash every line, and commenting how the function should be use forces you to have a massive block of comment, when I can just look in the code how that function is being used.

If you use visual studio, the comments come along with intellisense.  So a small comment can really help because I don't even have to switch documents, I can simply type the name (or something close) scroll until I see a function I think I'm looking for, and right away know what exactly it does, along with its parameters.

Also /* */ can't be nested (sadly) so I prefer to use in mainly for debugging when I need to quickly disable large sections and stick with // almost exclusively the rest of the time.

But other than that I agree with you, the google coding style seems a bit strange in many places.

Really, as long as its neat, clean, and consistent, its fine IMHO.  Oh and you should always use tabs not spaces... that one is a must!

[InfiniteStateMachine]

{ // open the scope
...
} // end the scope

  

I think you found a new contender. That's even worse than

// sets X
void SetX(int x)

[ProgramGamer]

i just put the comments on a line above the line of code instead of after it on the same line (with certain exceptions)

Can't do that lol, my prof wants a specific formatting.

...

Maybe I'm misunderstanding your issue but that should work fine if you select the code region and then go ctrl-k, ctrl-f. Or if you want to format the whole file ctrl-a,ctrl-k,ctrl-f

What I mean it that I have to format the comments at the end of lines of code so they all line up horizontally. kinda like this:

Code:

int something = 0;        // Comment 1
something = 2;            // Comment 2
std::cout << something;   // Comment 3

And I have to maintain that alignment throughout the file.

...

I'm going to go ahead and knock the learning benefit then. Seems utterly useless and like a waste of time to me tbh. Like this I imagine would blow up the time needed to finish an assignment immensely, while failing to teach how to write self documenting code. There's benefit in having to write some amount of comments to demonstrate understanding but I'm pretty sure one per line is just bullshit.

I mean yeah, it's time consuming, but then again I'm in college, and my prof has to look at my code and spend the least possible amount of time trying to figure out what it does, so it's probably just for the edge case where I write something that's obvious to me but obtuse to him.

{ // open the scope
...
} // end the scope

Don't joke about this kind of stuff, someone might get the brilliant idea of actually doing it lol

[InfiniteStateMachine]

oohh I see what you mean. I've felt that pain a bit. I used to align all my member declarations using tabs but auto format would mess all that up or someone would autoformat and submit it to source control.

It's too bad I really liked that formatting for members and variables. Kind of looked like a spreadsheet.

If you make that plugin for VS I'd be interested

[Ordnas]

oohh I see what you mean. I've felt that pain a bit. I used to align all my member declarations using tabs but auto format would mess all that up or someone would autoformat and submit it to source control.

It's too bad I really liked that formatting for members and variables. Kind of looked like a spreadsheet.

If you make that plugin for VS I'd be interested

I found CodeAlignment plugin:
https://marketplace.visualstudio.com/items?itemName=cpmcgrath.Codealignment

but I did not try it yet, and I cannot find if this works for comments. But in this one:
https://marketplace.visualstudio.com/items?itemName=wwm.better-align
the GIF shows that works for comments also.

[popawheelie]

Also /* */ can't be nested (sadly) so I prefer to use in mainly for debugging when I need to quickly disable large sections and stick with // almost exclusively the rest of the time.

Yes. Right on the money.