"Bulldozer code" - gives the appearance of refactoring by breaking out chunks into subroutines, but that are impossible to reuse in another context (very high cohesion)
Subroutine that is only used in one place still improves readability: instead of a bunch of statements, you have a name, explicit parameter list and a retugn value.
...and then that subroutine has another subroutine, each has its own *doc comments, and suddenly to understand the code you need to jump between three files and read 50 lines of code that could be five lines of code in one file.
Breaking up code doesn't always make it more clear and readable.
The same goes for OOP and desperately creating objects from things that don't represent real world entities.
I only agree with this in the case of pure functions. However, when your function has a side effect (quite usual in C++ methods for example) then all readability gains are lost.
I much prefer inlined code that reads from top to bottom, rather to have to jump all over the place into single purpose functions.
it's not when applied once, it's when something that can be understood more easily "locally" is exploded into a billion such pieces - then you have to mentally find all the call sites and usages to mentally build the call graph back up — you still have to understand how the whole ensemble works and bulldozing can (but not always) make understanding the ensemble more difficult especially if done by a poor programmer has the effect of obfuscation rather than clarification.
Vs the many lines of checking, creating the ConnectionFactory, passing in the the conditions to the ConnectionConditionFactory, and generally having a new statement every time you want to blow your nose. What were we doing again? I dunno.
I've used it. I'll defend it. It's better than comments when done properly as above.
What's the difference between cond1 and cond2 parameters? Can they be swapped? If cond1 and cond2 are booleans, they're almost indecipherable at the call site. Why not cond1 && cond2 (or symbolic equivalent)?
Abstracting away the gruntwork of your connection factory and your connection condition factory into a couple of separate routines - those are resuable bits of code, they'll let you write this code at a higher level of abstraction using reusable abstractions. But pushing the ugly wiring into a non-reusable black box and pretending it's better design - bullshit.
Good point on the conditions. I wanted to avoid pasting prod code I'd been working on and was trying to make an example: I generally use this for things like logging.
It's best when:
1) The logic is very specific to the situation and isn't reusable
2) Isn't important to the function's api contract.
More generally, functions are not only about abstraction, but also about decomposition.
The only thing that may hurt readability is when the decomposition itself is too much nested. Usually, it's best to split a large task purely linearly in subtasks (functions), and have them called all from a single function. That main task function gives you not only an overview of all sub tasks, but also about the dataflow between them.
In constrast, too much subtask nesting (subtasks of subtasks of subtasks) often hide the overall flow, which then makes it hard to get the overall view.
Code maintenance is hard, therefore a bugfix could easily turn the function to establish_connection_given_these_conditions_and_implicit_one(cond1, cond2);
Now the identifier is misleading and becomes a landmine waiting to blow your feet off :(
Having done some debugging where identifiers/comments/structure are misleading I am a bit afraid of such code.
I am really not sure what is the best way to structure highly imperative code though, because every option I have seen contains some dark corners.
Fair. On of the good aspects is that it makes this chunk testable, rather than having to test the behavior of the long line of statements. If there's a test for it it's a lot harder to sneak in an implicit assumption.
What I meant was that the implicit condition may be too context specific, dunno, maybe some NIC flags or something that are extremely unlikely to be caught by tests (especially written by anyone working on the code piece), code reviews or any such measure. Because the code works seemingly well until underlying conditions stop being satisfied.
Such conditions happen all the time, but are unproportionaly painful to debug in bulldozer code :(
Rant: Even though tests are nearly invaluable, though I personally believe that tests written by the same person writing implementation give a bit false sense of security. I see spec, tests and implementation different representations of author's understanding of the problem. If any two of those (e.g. tests and implementation) are produced from the same mind/understanding then they cannot be used to verify that understanding behind each other is the same.
Good point. I think I should make myself clear: I explicitly meant _procedures_ as in _functions_, most likely, pure ones, and not _methods_ of the same instance, for example. which have acccess to the same dozens of private members. If you can, declare these procedures to minimize their possible side effects - that makes reasoning about them much clearer.
The point is not to do that. When it is split into small pieces and I am validating the code, I care only about whether the content of function does what the name says. I don't need to have it all in head at the same time.
With no guarantee that the name corresponds with what it does (particularly 5 or 10 years in the future) and your parameter list doesn't have names at point of use (what does the 'true' argument do?) and may be overloaded.
Factoring things out into single-use subroutines is a real mixed bag. It's not a clear win at all, not at all.
While I don't think refactoring single use function is a win in every case, I think it makes sense when what you're trying to do in the block of code could be conceptually separated from the rest of the function - and named appropriately.
Arguments sometimes make this practice messy, especially if you find out that your detached subroutine requires 5 different arguments from its parent. But IDEs or smart editors with tooltips or goto-definition make this an almost no-brainer in most cases. Besides that, many languages allow you (or even force you in the case of Smalltalk and Objective C) to solve the argument readability problem at the language level. When it's really naked 'true', you could just use keyword arguments.
I used to agree with you but now I resoundingly do not. The only compelling reason I have left is still quite compelling: testability. Without breaking your code I to subroutines it becomes orders of magnitude harder to test effectively or at all.
Equivalent to the "multiRet" function there and, I think, easier to follow:
int multiRet() {
if (!a) return 0;
if (!b) return 1;
return c ? 2 : 0;
}
The singleRet function, as someone else already pointed out, actually has different behaviour (as well as being, in my view, just slightly harder to read and reason about):
int singleRet() {
if (!a) return 0;
return (b&&c) ? 2 : 1;
}
Both of these seem to me much much clearer than the multiply-nested versions there, and much clearer than introducing a new variable for the sake of a single return point.
(The other way to get a single return point here is to turn the code into a nest of ?: operators. I claim that will be less readable and more error-prone for most C programmers.)
I can't recall any instance I've ever seen where code became simpler or easier to follow as a result of turning multiple return points into a single return point.
WTF?? No it isn't. You have this magic initial value and have to figure out which code paths have mutated it and which haven't. Mutable variables make code far far more complex to read.
I'm all for single return but through the use of expressions, not variables; I would probably express the given function as:
expression() {
return
a ?
(b && c) ?
2
:
1
:
0
;
}
(Ideally I'd use a language that allowed a sensible conditional expression rather than one that relies on bizarre symbols, but we work with what's available)
let expression a b c = match (a, b, c) with
| (true, true, true) => 2,
| (true, true, _) => 1,
| (false, _, _) => 0
I like how pattern matching allows you to create something very close to a truth table. It allows you to visually see what's going on.
EDIT: Just realized that the two code examples in the parent's link don't even do the same... Look at the truth table, and look at the case of 1 1 0. The first code would indeed return 0, but not the second one. Derp.
> In the embedded world, I imagine it would be a good standard to force people to consider refactoring functions to their truth table.
It's not only a "good standard". It helps with verification: you can verify that the truth table is correct, and then that the function correctly implements that truth table. At least the former can sometimes be done formally.
> Curious how MISRA works out in practice.
Like every other standard, it depends on who's implementing it and with what tools, but it generally works out pretty well.
From the first paragraph on wikipedia: "Its aims are to facilitate code safety, security, portability and reliability in the context of embedded systems, specifically those systems programmed in ISO C / C90 / C99."
Java has better much better code safety than C (no pointers, gc, etc.) is portable via a VM, and is not used in embedded systems. It's also not specifically ISO C. MISRA was built do address certain issues with a certain language, in a certain environment. You shouldn't apply everything it recommends blindly to another language just because they both have conditions and return statements.
If you can explain to me why java benefits from having a single return statement, I would consider it. Otherwise, I refuse to blindly follow guidelines that were designed for different problems.
If you read this thread again, you'll see that someone recommended early returns to reduce nesting. I replied that some people are not allowed to do that (eg because they have to follow MISRA). There is no need to quote Wikipedia. None of the points raised in this thread pertains only to one programming language. I'm sure you'll find at least one style guide forbidding multiple returns for every language that has return statements.
This is getting ridiculous. The reason I quoted wikipedia was to explain why "MISRA wasn't written with java in mind". Will you argue otherwise?
> None of the points raised in this thread pertains only to one programming language.
Except you replied to a java problem with a C style guide.
> I'm sure you'll find at least one style guide forbidding multiple returns for every language that has return statements.
And if that guide can explain why java benefits from having a single return statement, I would consider it. Otherwise, I refuse to follow guidelines that were designed for different problems or cosmetic reasons.
But generally, if the code is too onerous to modify due to e.g. excessive use of closure-captured data, then the code usually deserves a long, hard ಠ_ಠ to make sure it doesn't deserve a (╯°□°)╯︵ ┻━┻. Hard to test, hard to fix, hard to control.
It's only "super hard" if you insist on anonymous classes. Reversing the `someCrap != null` condition and using an inner class reduces the identation count down to 2 (and that's in only one place for the return statement in the inverted null condition).
Also, consider using static imports for `Wearable.MessageApi.sendMessage` and `MessageApi.SendMessageResult`.
Personally I've never had this problem. The context was always sufficient, and a simple IDE shortcut can offer me any additional information. I would argue a double take is worth reducing the number of dots I have to follow when reading the code. Also, in the case of `Wearable.MessageApi.sendMessage`, you can statically import `MessageApi.sendMessage` which gives a little more context.
I really like being able to read code in source control historical diffs, pull requests, etc. IDE shortcuts aren't a full solution; not everyone has time to check out a branch at that commit, create a project (if necessary), fire up an IDE (if there's a UI available) just to understand a line of code. Similarly, static imports at the top of the file are usually remote from the point of use, so you lose that context when viewing a diff.
I needed to a fix a particular kernel protocol subsystem so I could use Linux at work. I sat down with the spec and a non-Linux computer that implemented it. I spent 8 weeks (I thought it would take a couple days--HAH!), and I wrote it and wrote the very nice test suite which included the single test case I couldn't handle (handling would have required major changes to the kernel).
It's a protocol. The word protocol means "state machine". Especially when hardware dudes design something.
However, state machines mean "indentation". One level for current state, one level (at least) for output variables, and a couple of levels for input variables. My code was well documented, tested, and easily changeable if you needed to add a new state.
"But, that's more than two levels of indentation. Rewrite it.".
After I pulled my jaw up off the floor, swore a couple of times, I replied: "No. This code is properly written, well-tested, and very amenable to changes when the spec gets updated. This code does what I need and what a bunch of people need. I will happily distribute it to them and you will have a bunch of users of this subsystem happily telling everybody to not use mainline because they are a bunch of tossers. If you wish to rewrite it to your indentation spec, feel free, but I will not sign off until it passes all of the tests."
So, they did. They decided to rewrite it to remove the indentation. Lots of early returns (full of bugs). State cases that got "simplified" by sharing common code (full of uninitialized variable bugs). And, because of all the sharing, it became difficult to add cases when the spec changed (which it did--regularly).
But, eventually they got their two levels of 8 character indent. After SIXTEEN WEEKS.
My question, of course, was "Why not just pull each state into a function? It was the obvious way to get what you want. It would have been much easier."
The response: "Well, we tried that. But there are so many variables per state, that the function calls were all exceeding an 80-character line length and we had to wrap them too much."
I had a bruise on my forehead that day.
Yeah, formatting rules exist and have good reasons. But please remember that the goal is "code quality and readability"--not formatting rules.
followed by indentation on the following block, would be turned by the programmer into something like:
if(someCrap == null) return; //nothing to do
without an indent following.
thereby saving the indent and having to have the reader keep track of another level.
How many times have you seen:
}
}
}
}
And is it really that great?
Breaking it into line by line is actually easier to follow than nested conditions. (You don't have to worry about proper indentation or matching braces properly, it's simply easier to write.)
I agree with you if that's all it were. But sometimes it's
if(someCrap == null) {
try {
CrapSurface mCrapSurface = CrapGenerator.generateSomeCrap(CrapGenerator.CRAPPY, new CrapFactory.CrapOptions(new CrapOptionsCallBack() {
@Override
int getHeight() { return 5; }
@Override
int getWidth() { return 9; }
}));
someCrap = CrapSurface.getCrap();
}
catch (SomeException e） {
try {
someOtherFailSafeButInefficientWayToGenerateTheCrap();
} catch (WeirdExceptionThatWillSeriouslyNeverHappenButStupidJavaRequiresMeToHaveATryCatchClauseAnyway f) {
// do nothing because this exception will never happen and if it happens the user deserves it
}
}
} else {
... the other code I had before ...
}
That's more readable and less indented. It's also self documenting.
} catch (WeirdExceptionThatWillSeriouslyNeverHappenButStupidJavaRequiresMeToHaveATryCatchClauseAnyway f) {
// do nothing because this exception will never happen and if it happens the user deserves it
}
Nice joke, don't do this. I don't believe it's the user's fault, and even so either print the stack trace or name the exception `ignored`. It's not that hard to pipe all ignored exceptions in a single catch.
Also, somebody made the conscious decision of making that exception checked, which means it's the implementor's fault for forcing you to catch it. If you want, you can use lombok's `@SneakyThrows`.
I like to think of plugins like this one playing a sort of "assistant" role rather than a "benevolent dictator" kind of role. So you don't have to end up making ugly hacks to just make it work.
Even without async/await, if you properly organize code in bite size functional blocks and use other asynchronous constructs then the indentation should be manageable.
Seriously though, it's super hard to avoid deeply-indented code in some languages (cough Java, JavaScript).