[QUOTE=WhyNott;52370864]This is what they say in Clean Code by Robert C. Martin, which is a book that I've been using for some time to improve my skills a little. You've made some trading websites so I guess you count as an experienced person, is your experience different?[/QUOTE]
yep
y'all need to read some Clean Code literature
[QUOTE=NotMeh;52370762]well-written code documents itself
there's no reason to write a comment if your code is readable on its own
you'd just be doing the same thing twice[/QUOTE]
Self-documenting code means the code is written well enough for someone to know the logic just by going through it.
In no way does it imply you write zero lines of comment. This is exactly how you piss off all other developers on your team.
[QUOTE=B!N4RY;52371645]Self-documenting code means the code is [B]written well enough for someone to know the logic just by going through it[/B]. In no way does it imply you write zero lines of comment. This is exactly how you piss off all other developers on your team.[/QUOTE]
what do you even mean by this?
you will know the logic of any and all code "just by going through it", regardless of how well it's written
clean code means that your code reads pretty much like a sentence in English
there's no need to type out its purpose a second time if it's 100% clear what it does just by looking at it once
[QUOTE=NotMeh;52371754]what do you even mean by this?
you will know the logic of any and all code "just by going through it", regardless of how well it's written
clean code means that your code reads pretty much like a sentence in English
there's no need to type out its purpose a second time if it's 100% clear what it does just by looking at it once[/QUOTE]
FYI, professional environments usually have very strict guidelines on commenting. What seems apparent to you is not always apparent to other developers when they go through your code.
If I want to know how you specifically implemented how a player fires a rocket, I want to be able to jump to the relevant section of the code and find and understand what I need right away without having to trace through the entire code base. The last thing I want to do is sort through 100 different .cpp files with dozens of helper functions in each file just to find the relevant section of code i'm wanting, just to realize I still don't know how it works when the code for firing rockets calls a dozen of other long and complicated functions that you wrote.
The code may seem easy to follow to you since you wrote it, but others wont' be able to obtain the exact state of your train of thoughts when you wrote the code. This is why comments are important. People don't have time to trace through your entire code just to understand something completely unrelated, and comments also helps other in understanding your rationales when you wrote the code.
[QUOTE=B!N4RY;52371776]FYI, professional environments usually have very strict guidelines on commenting. What seems apparent to you is not always apparent to other developers when they go through your code.
If I want to know how you specifically implemented how a player fires a rocket, I want to be able to jump to the relevant section of the code and find and understand what I need right away without having to trace through the entire code base. The last thing I want to do is sort through 100 different .cpp files with dozens of helper functions in each file just to find the relevant section of code i'm wanting, just to realize I still don't know how it works when the code for firing rockets calls a dozen of other long and complicated functions that you wrote.
The code may seem easy to follow to you since you wrote it, but others wont' be able to obtain the exact state of your train of thoughts when you wrote the code. This is why comments are important. People don't have time to trace through your entire code just to understand something completely unrelated, and comments also helps other in understanding your rationales when you wrote the code.[/QUOTE]
I do understand the idea, but the whole purpose of Clean Code is to make it seem like the entire codebase was written by a single person, in the same style, structure and using commonly known and defined patterns
in my opinion, rather than creating strict guidelines for commenting, stricter guidelines on code style, structure and architecture should be prioritized
every line should follow the same general 'standard' and as soon as a new programmer has grasped that standard, they shouldn't have to rely on comments to understand what's going on
edit:
the other problem with comments and documentation in general is that keeping it up-to-date with the actual codebase is often quite difficult
rather, it's easy to neglect it and create misleading documentation
when your documentation stops matching the actual code (which in this context, is the 'absolute truth' of how the program functions), it's not only useless but potentially quite harmful
The standard where I work is no comments and to set the tab key to indent 4 spaces. Comments just waste the code reviewer's time.
[editline]18th June 2017[/editline]
[QUOTE=B!N4RY;52371776]FYI, professional environments usually have very strict guidelines on commenting. What seems apparent to you is not always apparent to other developers when they go through your code.
If I want to know how you specifically implemented how a player fires a rocket, I want to be able to jump to the relevant section of the code and find and understand what I need right away without having to trace through the entire code base. The last thing I want to do is sort through 100 different .cpp files with dozens of helper functions in each file just to find the relevant section of code i'm wanting, just to realize I still don't know how it works when the code for firing rockets calls a dozen of other long and complicated functions that you wrote.
[B]The code may seem easy to follow to you since you wrote it, but others wont' be able to obtain the exact state of your train of thoughts when you wrote the code. This is why comments are important. People don't have time to trace through your entire code just to understand something completely unrelated, and comments also helps other in understanding your rationales when you wrote the code.[/B][/QUOTE]
This is part of the reason why peer review exists. If your code is convoluted, you need to rewrite it.
[QUOTE=NotMeh;52371825]I do understand the idea, but the whole purpose of Clean Code is to make it seem like the entire codebase was written by a single person, in the same style, structure and using commonly known and defined patterns
in my opinion, rather than creating strict guidelines for commenting, stricter guidelines on code style, structure and architecture should be prioritized
every line should follow the same general 'standard' and as soon as a new programmer has grasped that standard, they shouldn't have to rely on comments to understand what's going on[/QUOTE]
Guidelines for commenting is a subset of the overall guidelines for code-style. They are not mutually exclusive. They are both practiced in professional environments and you're expected to follow both.
[QUOTE=squids_eye;52372238]This is part of the reason why peer review exists. If your code is convoluted, you need to rewrite it.[/QUOTE]
Code review is definitely important, but I should clarify that I don't mean [I]no one else[/I] understands the code you wrote, but [I]some[/I] won't.
As an example, developers from significantly different disciplines will have a hard time understand the work from another department (eg, physics vs animations), and same with developers who's new to the code base altogether. It's going to be very difficult for developers working on animations mechanisms to understand the logic in the work done by the physics department without any comments in their code.
[QUOTE=squids_eye;52372238]The standard where I work is no comments
[/QUOTE]
Boy am I glad I don't work where you work, then.
I'll be the first to admit that there is such a thing as [b]over-[/b]commenting, and that over-commenting can slow down reading through the code unnecessarily. And I will admit that most academic standards I've been exposed to consist of over-commenting.
But no comments at all is just unhelpful for everyone involved - including yourself, when you return to it after 8 months and a dozen projects. You don't need anything super complicated, just a quick sentence fragment explaining what a chunk of code does, like this:
[code] // Iterate through the pixels
for (int i=0; i < newBmpData.Length; i += 4)
{
// Get the original RGBA values of the normal and the specular
sourceBlue = newBmpData[i];
sourceGreen = newBmpData[i + 1];
sourceRed = newBmpData[i + 2];
sourceAlpha = newBmpData[i + 3];
specBlue = newSpecData[i];
specGreen = newSpecData[i + 1];
specRed = newSpecData[i + 2];
specAlpha = newSpecData[i + 3];
resultSpec = specBlue;
// Copy the alpha over to the green channel, max out the blue channel, and copy the specular over to the alpha
resultRed = sourceRed;
resultGreen = sourceAlpha;
resultBlue = nmBlue;
resultAlpha = resultSpec;
// And then write these new values into the image.
newBmpData[i] = resultBlue;
newBmpData[i + 1] = resultGreen;
newBmpData[i + 2] = resultRed;
newBmpData[i + 3] = resultAlpha;
}[/code]
what i usually do is if it takes me more than a few seconds to realize the purpose of a line of code then i should probably comment it.
[QUOTE=Gmod4ever;52372527]Boy am I glad I don't work where you work, then.
I'll be the first to admit that there is such a thing as [b]over-[/b]commenting, and that over-commenting can slow down reading through the code unnecessarily. And I will admit that most academic standards I've been exposed to consist of over-commenting.
But no comments at all is just unhelpful for everyone involved - including yourself, when you return to it after 8 months and a dozen projects. You don't need anything super complicated, just a quick sentence fragment explaining what a chunk of code does, like this:
[code] // Iterate through the pixels
for (int i=0; i < newBmpData.Length; i += 4)
{
// Get the original RGBA values of the normal and the specular
sourceBlue = newBmpData[i];
sourceGreen = newBmpData[i + 1];
sourceRed = newBmpData[i + 2];
sourceAlpha = newBmpData[i + 3];
specBlue = newSpecData[i];
specGreen = newSpecData[i + 1];
specRed = newSpecData[i + 2];
specAlpha = newSpecData[i + 3];
resultSpec = specBlue;
// Copy the alpha over to the green channel, max out the blue channel, and copy the specular over to the alpha
resultRed = sourceRed;
resultGreen = sourceAlpha;
resultBlue = nmBlue;
resultAlpha = resultSpec;
// And then write these new values into the image.
newBmpData[i] = resultBlue;
newBmpData[i + 1] = resultGreen;
newBmpData[i + 2] = resultRed;
newBmpData[i + 3] = resultAlpha;
}[/code][/QUOTE]
Now, I'm obviously not a very experienced programmer but I think the problem here is that you are mostly just using weird and unreadable variable names that need further explanation.
From the looks of it:
• The comment about iterating through the pixels is kinda legit, but I don't really think that anyone would be confused as to what this loop does anyway. I give point to you, since you can't obviously name loops
• If you named the variables originalNormalBlue, originalNormalGreen, originalSpecularBlue, orginalSpecularGreen and so on, you can make the second comment 100% redundant
• Next comment may be legit but I think you could convey the same message by just making the operations go in the order you are explaining them in comment, rather then sticking to the rgba order
• Last comment is already pretty unnecessary, but if you wanted to make sure that even a total newbie would understand it you can change the newBmpData variable name to something like newBmpImageData if you really wanted for anyone to understand the connection
As I said, I'm not trying to tell you how to do your job, I obviously don't know as much about programming as you do, I just think you're wrong with that the comments are necessary in the example you gave
[QUOTE=WhyNott;52373747]Now, I'm obviously not a very experienced programmer but I think the problem here is that you are mostly just using weird and unreadable variable names that need further explanation.
From the looks of it:
• The comment about iterating through the pixels is kinda legit, but I don't really think that anyone would be confused as to what this loop does anyway. I give point to you, since you can't obviously name loops
• If you named the variables originalNormalBlue, originalNormalGreen, originalSpecularBlue, orginalSpecularGreen and so on, you can make the second comment 100% redundant
• Next comment may be legit but I think you could convey the same message by just making the operations go in the order you are explaining them in comment, rather then sticking to the rgba order
• Last comment is already pretty unnecessary, but if you wanted to make sure that even a total newbie would understand it you can change the newBmpData variable name to something like newBmpImageData if you really wanted for anyone to understand the connection
As I said, I'm not trying to tell you how to do your job, I obviously don't know as much about programming as you do, I just think you're wrong with that the comments are necessary in the example you gave[/QUOTE]
These comments seems unnecessary because you saw them already and that made the code easier to understand.
I doubt you really knows what datatype "newBmpData" actually is (and what it does in the big picture) out of context without the aid of any comments.
Well obviously I only know those things because I saw the comments. Thats not my point. With right variable names those information could be conveyed without the need for comments.
[editline]18th June 2017[/editline]
Your point about the newBmpData actually proves my point right - you cant tell what datatype it is without the comments, and hence its a bad name.
Sure, someone can read the names of all the variables, look at what they're doing, think of the context and figure out what the code does
Or they can just read a single line comment that tells you what that whole block does
You're just trying to justify being too lazy to write comments, clean code doesn't mean anything when it's still a pain in the ass to trudge through it trying to work out what every part does
[QUOTE=kaze4159;52373935]Sure, someone can read the names of all the variables, look at what they're doing, think of the context and figure out what the code does
Or they can just read a single line comment that tells you what that whole block does
You're just trying to justify being too lazy to write comments, clean code doesn't mean anything when it's still a pain in the ass to trudge through it trying to work out what every part does[/QUOTE]
Indeed, why on earth would I want to read each line of code and try to figure out how it all comes together when I can read 4 comments summarizing the entire function? No comments is just atrocious, I do not know how you can justify no commenting with "clean code", what on earth are you going on about WhyNott. Try "clean coding" 3d vector space functions without comments and see how well that works out in efficiency of understanding for everyone on the team
I prefer tab because whoever is programming can (in most cases) change how wide the indentation is as a setting on whatever editor they are using, without changing the code itself, and with tab it is just a single key press to indent. Am genuinely curious though, what is the reason some people prefer spaces?
[quote]$15,370 (£12,000)[/quote]
I can understand a small difference due to paying by silly things like characters typed or just some statistical coincidences but why the fuck is this number so high?!
You should try to write understandable code and use self-explanatory variable/function names if possible but obviously sometimes comments are still needed.
[editline]18th June 2017[/editline]
[QUOTE=daigennki;52374039]I prefer tab because whoever is programming can (in most cases) change how wide the indentation is as a setting on whatever editor they are using, without changing the code itself, and with tab it is just a single key press to indent. Am genuinely curious though, what is the reason some people prefer spaces?[/QUOTE]
I think that's exactly the reason why some people prefer spaces: they look the same for everyone.
[QUOTE=B!N4RY;52373814]These comments seems unnecessary because you saw them already and that made the code easier to understand.
I doubt you really knows what datatype [B]"newBmpData" actually is (and what it does in the big picture)[/B] out of context without the aid of any comments.[/QUOTE]
part of that meaning should reside in the name of the variable, as already mentioned
and if that really is a different data type, then its purpose should reside where that data type is initially defined, whether it's a class definition or field definition, not in some random chunk of the code
and if that data type is used in more than a single place, will you also write the exact same comment in more than one such chunk of code?
keeping it up-to-date with the actual functionality will henceforth become even more of a nightmare
[editline]18th June 2017[/editline]
[QUOTE=t h e;52373964]Indeed, why on earth would I want to read each line of code and try to figure out how it all comes together when I can read 4 comments summarizing the entire function? No comments is just atrocious, I do not know how you can justify no commenting with "clean code", what on earth are you going on about WhyNott. Try "clean coding" 3d vector space functions without comments and see how well that works out in efficiency of understanding for everyone on the team[/QUOTE]
maybe you should actually read the book instead of criticizing something you have obviously zero knowledge of
Tabs vs spaces, curly brackets sameline vs newline, and comment frequency are all personal preference.
I'll never understand arguing to the point of flaming over programming preferences that don't affect you. These kinds of discussion only hold merit in a team setting where code has to be consistent.
[QUOTE=ZestyLemons;52374105]Tabs vs spaces, curly brackets sameline vs newline, and comment frequency are all personal preference.
I'll never understand arguing to the point of flaming over programming preferences that don't affect you. These kinds of discussion only hold merit in a team setting where code has to be consistent.[/QUOTE]
I think it can make for an interesting discussion
tho yeah mostly it devolves into dumb shitflinging really quick
[QUOTE=ZestyLemons;52374105]Tabs vs spaces, curly brackets sameline vs newline, and comment frequency are all personal preference.
I'll never understand arguing to the point of flaming over programming preferences that don't affect you. These kinds of discussion only hold merit in a team setting where code has to be consistent.[/QUOTE]
I only really got into this discussion in the first place because Im a beginning programmer and I just wanted to hear how the advice from a book I bought hold up against actual work. It seems like in the end it all boils down to personal preference and whatever works best for you.
It wasnt my intention to start baptising and converting anyone to clean code ideology, just hearing what people this of its basic assumptions, sorry if I come off as the former
As long as you are consistent, I don't think there is a wrong answer.
[QUOTE=NotMeh;52374113][B]I think it can make for an interesting discussion[/B]
tho yeah mostly it devolves into dumb shitflinging really quick[/QUOTE]
No it doesn't , neither are objectively superior and it really doesn't matter which one you use, and these "discussions" always end in the same stalemate.
[QUOTE=WhyNott;52373747]Now, I'm obviously not a very experienced programmer but I think the problem here is that you are mostly just using weird and unreadable variable names that need further explanation.
As I said, I'm not trying to tell you how to do your job, I obviously don't know as much about programming as you do, I just think you're wrong with that the comments are necessary in the example you gave[/QUOTE]
The variable names are actually perfect for what they are doing. The good thing about that style of commenting is that the comments acts a kind of flowchart, which is really nice when you have no idea what it's doing after you're coming back to work from the weekend, or are reading someone else's [del]shit[/del]work
Tell me more about the flowchart. What do you mean by that? For me some of the variable names in that example were just weird and illogical. Like how the set of variables for the normal had prefix "source" while the ones from the specular had prefix "specular"
[QUOTE=WhyNott;52374322]Tell me more about the flowchart. What do you mean by that?[/QUOTE]
By flowchart I mean having something that describes how the program works if I wouldn't have to go in depth, like you usually would with a flowchart. If you take out all the programming and leave only the comments, like so:
[code]
// Iterate through the pixels
// Get the original RGBA values of the normal and the specular
// Copy the alpha over to the green channel, max out the blue channel, and copy the specular over to the alpha
// And then write these new values into the image.
[/code]
Congratulations, you now have a pretty good understanding of the function of the program, without actually having to analyse any of the code. Here's something that I wrote a while ago pretty much on a binge where I forgot to add comments.
[code]
// Detect edges
void edgeDetection(float friction) {
if (location.x + dHalf >= width) {
velocity.x *= -1;
location.x = width - dHalf;
this.applyFriction(friction);
}
if (location.x - dHalf <= 0) {
velocity.x *= -1;
this.location.x = dHalf;
this.applyFriction(friction);
}
if (location.y + dHalf >= height) {
velocity.y *= -1;
location.y = height - dHalf;
this.applyFriction(friction);
}
}
[/code]
Looking back at it, :sick:. Having to debug something like that sucks hard, because it's not immediately what the program does
I think I know now why the clean code way seems easier to me. I'm never good with words and expressing myself clearly, so if I have to convey a message as to what a program does, I might as well do it via the code itself :v: This way I also don't have to worry with what counts as important information
[QUOTE=gokiyono;52374365]By flowchart I mean having something that describes how the program works if I wouldn't have to go in depth, like you usually would with a flowchart. If you take out all the programming and leave only the comments, like so:
[code]
// Iterate through the pixels
// Get the original RGBA values of the normal and the specular
// Copy the alpha over to the green channel, max out the blue channel, and copy the specular over to the alpha
// And then write these new values into the image.
[/code]
Congratulations, you now have a pretty good understanding of the function of the program, without actually having to analyse any of the code.
[/QUOTE]
Yep, that's pretty much exactly what I shoot for.
I generally first design these functions / programs / whatever on a mental pen-and-paper pad, with a sort of checklist (or, as you say, a flowchart) of what the function / program / whatever needs to do.
Then, when I write the code out, I drop each checklist (or flowchart) item as a comment, so I can quickly see what all I've done and what all I still need to do.
It's a sort of shorthand for myself, if nothing else.
It's doubly useful when I actually physically write down all the steps, and don't get to finish implementing it all before having to take an extended break from it. Then, when I return to it, I just pull out that pen-and-paper, and scroll through all of the code until the last comment, and then see where that is on the checklist, and keep going from there.
I won't lie when I say, I wasn't expecting my shitty code segment from a quick program I wrote to batch-port Sins of a Solar Empire models to the Source engine to merit a more-or-less whole page of discussion.
I feel oddly honored. :smile:
[QUOTE=C0linSSX;52367376]Tabs for basic indentation, spaces for additional alignment. Anything else is objectively inferior[/QUOTE]
...is there something to coding environments that lets you even use tab for that? Every time I hit tab in a text editor it either does nothing or leaves the text editor to highlight the next clickable item on the page.
[QUOTE=NotMeh;52374075]part of that meaning should reside in the name of the variable, as already mentioned
and if that really is a different data type, then its purpose should reside where that data type is initially defined, whether it's a class definition or field definition, not in some random chunk of the code
and if that data type is used in more than a single place, will you also write the exact same comment in more than one such chunk of code?
keeping it up-to-date with the actual functionality will henceforth become even more of a nightmare
[editline]18th June 2017[/editline]
maybe you should actually read the book instead of criticizing something you have obviously zero knowledge of[/QUOTE]
Obviously it's clear I haven't read the book and I'm not going to read it to criticize one point in this entire thread, but saying clean coding can substitute and compensate for no comments is just ridiculous; no amount of clear cut variable names & structure is going to make understanding complex functions just as efficient, was the point I was trying to make. I realize that I'm actually arguing against a point that wasn't really that contended, which is that you don't need comments to code if your code is written well enough, but looking back on it now, you never really stated that, it really sounds like initially that's what you were implying. Unless you actually do believe that you don't need comments because clear coding is enough, then I still contest that
Sorry, you need to Log In to post a reply to this thread.