AND ONE OF THESE PROVIDES USEFUL INFORMATION WHEN YOUR FUCKING INSANE "MANUALLY EDIT /ETC/PASSWD/ AND DON'T USE THE SYSTEM TOOLS" CODE BREAKS!
I feel like a specific event drove you to provide us with this quick protip.
Near as I can tell, the comment in question was added several years after the original code. I think the original code predates our platform having a version of BusyBox 'adduser' that supports the '-u UID' flag, but I'm pretty sure the entire block could have been deleted by the time the comment was added.
Either way, I replaced ~40 lines of file editing code with 4 characters and fixed like 3 bugs simultaneously, so
every comment is someone making an excuse for their insufficiently expressive code
Code, no matter how expressive, can only tell you "what". It can't tell you "why", and when you're staring at something trying to figure out what in the ever-loving hell they (or you) were smoking when they did this thing once upon a time, a comment to the effect of "this horrible hack exists because..." can be a welcome sight.
Edit: And not that this has ever happened no, but it also means you won't break something by "fixing" the clearly awful and inappropriate way someone did something once upon a time into something more elegant.
every comment is someone making an excuse for their insufficiently expressive code
Code, no matter how expressive, can only tell you "what". It can't tell you "why", and when you're staring at something trying to figure out what in the ever-loving hell they (or you) were smoking when they did this thing once upon a time, a comment to the effect of "this horrible hack exists because..." can be a welcome sight.
Edit: And not that this has ever happened no, but it also means you won't break something by "fixing" the clearly awful and inappropriate way someone did something once upon a time into something more elegant.
every comment is someone making an excuse for their insufficiently expressive code
Code, no matter how expressive, can only tell you "what". It can't tell you "why", and when you're staring at something trying to figure out what in the ever-loving hell they (or you) were smoking when they did this thing once upon a time, a comment to the effect of "this horrible hack exists because..." can be a welcome sight.
Edit: And not that this has ever happened no, but it also means you won't break something by "fixing" the clearly awful and inappropriate way someone did something once upon a time into something more elegant.
Where "Foo" is described in excruciating detail? That's what the comment is for. Comments are also useful for ASCII art (not common, but sometimes a picture of a waveform is worth a thousand words).
Interesting fact: In Elixir, you can UNIT TEST comments. If your comment has function calls with sample inputs and outputs, you can unit test that to make sure your comment stays accurate even as the code changes.
This is great, because a lot of times comments go stale and once you mistrust them they become useless.
+1
Options
OrcaAlso known as EspressosaurusWrexRegistered Userregular
edited March 2017
For example, in the codebase there is a complicated wait-for-state before certain actions can be taken due to an RTL bug. If the conditions aren't correct, this can result in a state machine within the ASIC getting stuck until the reset pin is pulled or power is cycled. It's unlikely to occur, but our complicated machinery keeps it from ever occuring.
There is a long, detailed comment detailing exactly what is wrong, how this series of function calls works around it, and a link to the issue tracker for when the bug is fixed.
You're never going to squash that into WorkAroundForRTLBug, but you can have a nice friendly write_sensitive_register() function that does all the error checking for you, and make sure it's suitably annotated.
every comment is someone making an excuse for their insufficiently expressive code
Code, no matter how expressive, can only tell you "what". It can't tell you "why", and when you're staring at something trying to figure out what in the ever-loving hell they (or you) were smoking when they did this thing once upon a time, a comment to the effect of "this horrible hack exists because..." can be a welcome sight.
Edit: And not that this has ever happened no, but it also means you won't break something by "fixing" the clearly awful and inappropriate way someone did something once upon a time into something more elegant.
As said, sometimes you can't get enough detail. Say you've got an AWS SDK issue that means you've had to code around some dumb incompatibility (hello TLS how are you) they haven't fixed yet because we're Amazon screw you. There's no real sane way to name your anything with enough detail to encapsulate the stupid you've had to deal with, unless you go full Java on it with a 100-something character name.
So, you name something "setupSQS" and put a comment explaining why you're duct taping it, instead of "setupSQSOldTLSVersion" which while it described what you're doing, doesn't tell Future You why in the hell you did that thing. Was it backwards compatibility? A workaround? Customer requirement? Even more so if your buddy Jill takes over maintenance 6 months from now, and has absolutely no idea why that's there, and now has to ask you about it.
Actually, my favorite real-life example of this is an iOS webview that just WOULD NOT render properly... Unless you put two lines of logging in the JS to find out why it wouldn't render properly. It's an absolutely idiotic fix, and without a comment Jill's going to go "hell why's that there?" and delete it, because who puts logging in shipped, minified code?
Edit: Unit testing comments. Wow. Now if I ever get to work with devs who want to write their own tests...
dporowski on
0
Options
OrcaAlso known as EspressosaurusWrexRegistered Userregular
edited March 2017
Oooh, here's an even better one: we're using a PI loop (which is the loop filter for a certain block) to do a frequency sweep instead of the dedicated frequency sweep hardware because it does a better job. This is bloody bizarre, so I put about 100 lines of comments in there explaining why this is valid, why it's better, and included pretty graphs showing how it works.
That's not fitting into a function name, when at a higher level all we care about is that the frequency sweep is done.
Orca on
0
Options
OrcaAlso known as EspressosaurusWrexRegistered Userregular
I mean, overall I agree with the sentiment that a comment means you have failed--but sometimes there is no way to succeed.
I appreciate self-documenting code, but sometimes the context is too complicated.
Personally, assuming the comments aren't so old they're a lie now, I'd always much rather read "this bit widgets the twiddler" as opposed to however many lines of dense whatever it takes to pull that off.
Sure, the code can be obvious, but I'm human, and parse humanese a lot faster than I do computer.
Sometimes you need to communicate something about why the code is, rather than what.
Optimisation's a big one here: you're doing something for other-than-functionality reasons, making the code a little less obvious and readable - then you want a comment explaining why so people don't come along and make it "better" without understanding the context.
I think self-commenting code is a great ideal to aim for, and try to make all my methods and variables clearly named so anyone can skim my code and understand what's happening. But sometimes, it's just not possible, because you're doing something complex or not obvious, and comments are there to explain it. I recently made a complex method and could have broken it apart into doesComplexStuff() and shufflesDataAround() and whatnot, but that would have just split the complexity into smaller, complex pieces, and scattered them about. It was more clear to the teammates who reviewed and later modified that code as a complex method with comments explaining what the data looked like at that step, what I needed to get from it, and so on.
I feel like this goes back to intrinsic vs extrinsic complexity. Self commenting code is great at reducing extrinsic complexity (where code is more complex than it needs to be) but sometimes you're working with something that is legitimately complex, and the code you write to deal with it will always be complex, so you should use comments to explain yourself.
i actually like doing condition == true these days because it makes the intent of the programmer completely clear
its easy to fuckup and forget a ! and not even notice, but quite a bit harder to accidentally type "false" when you wanted "true"
Yeah, I kind of dislike long statements like !Foo.Bar(pants).Where(lotsoflinq).Contains(bleh), because you have a Contains that returns a bool in one end, and the negation in the opposite end. By the time you've parsed it and reached the end you tend to have forgotten the negation at the start.
edit: I'd prefer having a NotContains() or something instead, much clearer intent.
Echo on
0
Options
OrcaAlso known as EspressosaurusWrexRegistered Userregular
If you're going to negate it, I like:
if (not condition) { ... }
But apparently that looks weird to most C++ coders.
Bumbling along with my little IRC server practice project. Ended up being only ~100 lines for all the code needed to accept connections, receive IRC protocol commands and pass them along to a registered handler method for that command if one exists.
Actually, this might be a good opportunity to mess with an actual GUI app to make a simple client to connect to the server. Never really done WPF/Forms stuff.
Actually, this might be a good opportunity to mess with an actual GUI app to make a simple client to connect to the server. Never really done WPF/Forms stuff.
WPF is a pleasure
take the time to learn it
not a doctor, not a lawyer, examples I use may not be fully researched so don't take out of context plz, don't @ me
I don't always do it like that, but if I find myself ever having to reuse the same set of conditionals then yeah I extract that.
yup same
if it's more than 1 or 2 boolean checks, I simplify it out
I often extract even for a single boolean check if the check is sufficiently complex or if the line it's written on is sufficiently long.
Like if for instance there's two separate conditionals, each of which with two values, each of which are accessed via method, that's a long snippet. I'll pull that out as long as I'm using it more than zero times.
And vaguely related, I like doing that with LINQ stuff, because oh boy can that get long. Deferred execution means you can just chop it up on however many lines you want.
edit: though usually I just end up doing it as a multi-line statement,
There are some monstrously long LINQ / EF statements in our code base. I always wonder if we abuse it, because LINQ makes it pretty easy to read and understand relatively long queries. Especially when compared to the equivalent monstrously long SQL queries.
Yeah I am decent (for a student) with T-SQL (and feel like I could pick up any of the others pretty easily as well). I noticed that LINQ looked a lot like SQL, only out of order.
inherited a code base from my client where every one of their customers was its own branch in the git repo
5 year old code base. probably 100+ customers. they just kept branching and committing forward and whenever they had a new client they picked the branch they liked the most and that effectively became the master
no deleted branches
+13
Options
mightyjongyoSour CrrmEast Bay, CaliforniaRegistered Userregular
haha that sounds like the division we just put up for sale... same sort of deal. even better, each customer had a different developer, so sometimes they just cloned the repo and continued branching, whistling all the way.
....this client isn't from Massachusetts, is it...?
i think this is pretty typical behavior for people who have no idea what source control is actually for, but know that employers like it. i've just never seen it... used to this extent
the only thing that comes close is i once had a contractor check in their entire C drive to SVN
i think this is pretty typical behavior for people who have no idea what source control is actually for, but know that employers like it. i've just never seen it... used to this extent
the only thing that comes close is i once had a contractor check in their entire C drive to SVN
I recall reading an article where a linux user had done something similar with git, just commited eeeeeverything. Someone saw this, decided to be nosey, pulled it all down and had a poke around.
Turns out the guy had some seriously unsavoury downloads (or nzbs/torrents for said files) on his computer.
And so he was arrested for owning child pornography (the original owner, not the nosey dude).
inherited a code base from my client where every one of their customers was its own branch in the git repo
5 year old code base. probably 100+ customers. they just kept branching and committing forward and whenever they had a new client they picked the branch they liked the most and that effectively became the master
no deleted branches
At my first job, we had the opposite problem. Our CTO had heard that developing on the main branch was how the big boys did it, so he put down a rule from on high that we were never supposed to branch, ever.
One time, in order to fix a bug for a client, we had to cut an emergency branch and deploy to fix the problem for them. We both almost got fired.
Posts
Near as I can tell, the comment in question was added several years after the original code. I think the original code predates our platform having a version of BusyBox 'adduser' that supports the '-u UID' flag, but I'm pretty sure the entire block could have been deleted by the time the comment was added.
Either way, I replaced ~40 lines of file editing code with 4 characters and fixed like 3 bugs simultaneously, so
Code, no matter how expressive, can only tell you "what". It can't tell you "why", and when you're staring at something trying to figure out what in the ever-loving hell they (or you) were smoking when they did this thing once upon a time, a comment to the effect of "this horrible hack exists because..." can be a welcome sight.
Edit: And not that this has ever happened no, but it also means you won't break something by "fixing" the clearly awful and inappropriate way someone did something once upon a time into something more elegant.
extract method -> HorribleHackThatExistsBecauseFoo(params)
Where "Foo" is described in excruciating detail? That's what the comment is for. Comments are also useful for ASCII art (not common, but sometimes a picture of a waveform is worth a thousand words).
Sometimes it'll be a comment that explains some stuff. Other times you can name a function/shim so that it's obvious why it's there.
If there was a simple and elegant rule that suited all situations, we'd have it automated by now. =P
This is great, because a lot of times comments go stale and once you mistrust them they become useless.
There is a long, detailed comment detailing exactly what is wrong, how this series of function calls works around it, and a link to the issue tracker for when the bug is fixed.
You're never going to squash that into WorkAroundForRTLBug, but you can have a nice friendly write_sensitive_register() function that does all the error checking for you, and make sure it's suitably annotated.
As said, sometimes you can't get enough detail. Say you've got an AWS SDK issue that means you've had to code around some dumb incompatibility (hello TLS how are you) they haven't fixed yet because we're Amazon screw you. There's no real sane way to name your anything with enough detail to encapsulate the stupid you've had to deal with, unless you go full Java on it with a 100-something character name.
So, you name something "setupSQS" and put a comment explaining why you're duct taping it, instead of "setupSQSOldTLSVersion" which while it described what you're doing, doesn't tell Future You why in the hell you did that thing. Was it backwards compatibility? A workaround? Customer requirement? Even more so if your buddy Jill takes over maintenance 6 months from now, and has absolutely no idea why that's there, and now has to ask you about it.
Actually, my favorite real-life example of this is an iOS webview that just WOULD NOT render properly... Unless you put two lines of logging in the JS to find out why it wouldn't render properly. It's an absolutely idiotic fix, and without a comment Jill's going to go "hell why's that there?" and delete it, because who puts logging in shipped, minified code?
Edit: Unit testing comments. Wow. Now if I ever get to work with devs who want to write their own tests...
That's not fitting into a function name, when at a higher level all we care about is that the frequency sweep is done.
I appreciate self-documenting code, but sometimes the context is too complicated.
Sure, the code can be obvious, but I'm human, and parse humanese a lot faster than I do computer.
Optimisation's a big one here: you're doing something for other-than-functionality reasons, making the code a little less obvious and readable - then you want a comment explaining why so people don't come along and make it "better" without understanding the context.
I feel like this goes back to intrinsic vs extrinsic complexity. Self commenting code is great at reducing extrinsic complexity (where code is more complex than it needs to be) but sometimes you're working with something that is legitimately complex, and the code you write to deal with it will always be complex, so you should use comments to explain yourself.
Coincidence! Just last week, I was looking over Co-Worker's code, and I had to laugh (as politely as was possible) at damn near the same thing:
siiiigh
My brain had to stop for a moment to be sure I was looking at what I thought I was. I got a kick out of the ".ToLower()" calls too.
I mean.. that could potentially be a legitimate check, if not verbose!
its easy to fuckup and forget a ! and not even notice, but quite a bit harder to accidentally type "false" when you wanted "true"
Yeah, I kind of dislike long statements like !Foo.Bar(pants).Where(lotsoflinq).Contains(bleh), because you have a Contains that returns a bool in one end, and the negation in the opposite end. By the time you've parsed it and reached the end you tend to have forgotten the negation at the start.
edit: I'd prefer having a NotContains() or something instead, much clearer intent.
if (not condition) { ... }But apparently that looks weird to most C++ coders.
Unless/When should be idiomatic single branch conditionals in any language where the construct exists.
Yeah. Either that, or go crosseyed.
WPF is a pleasure
take the time to learn it
I tend to do things like this:
bool itemShouldBeProcessed = (not condition) && (other condition); if(itemShouldBeProcessed) { ... }yup same
if it's more than 1 or 2 boolean checks, I simplify it out
I often extract even for a single boolean check if the check is sufficiently complex or if the line it's written on is sufficiently long.
Like if for instance there's two separate conditionals, each of which with two values, each of which are accessed via method, that's a long snippet. I'll pull that out as long as I'm using it more than zero times.
edit: though usually I just end up doing it as a multi-line statement,
etc etc.
And I have to find someone to do an "informational interview" with. Ugh, I forgot about this and now it is nearly due.
If you know any SQL, you're pretty much already there.
5 year old code base. probably 100+ customers. they just kept branching and committing forward and whenever they had a new client they picked the branch they liked the most and that effectively became the master
no deleted branches
....this client isn't from Massachusetts, is it...?
i think this is pretty typical behavior for people who have no idea what source control is actually for, but know that employers like it. i've just never seen it... used to this extent
the only thing that comes close is i once had a contractor check in their entire C drive to SVN
I recall reading an article where a linux user had done something similar with git, just commited eeeeeverything. Someone saw this, decided to be nosey, pulled it all down and had a poke around.
Turns out the guy had some seriously unsavoury downloads (or nzbs/torrents for said files) on his computer.
And so he was arrested for owning child pornography (the original owner, not the nosey dude).
http://steamcommunity.com/id/pablocampy
At my first job, we had the opposite problem. Our CTO had heard that developing on the main branch was how the big boys did it, so he put down a rule from on high that we were never supposed to branch, ever.
One time, in order to fix a bug for a client, we had to cut an emergency branch and deploy to fix the problem for them. We both almost got fired.
There's a reason I left that job.