4 ms·

This is a great write up and should be necessary read for every novice (and not so novice) programmer. That said, I would compose list "What makes code hard to

by annnnd 12y ago

This is a great write up and should be necessary read for every novice (and not so novice) programmer. That said, I would compose list "What makes code hard to understand?" differently: 1) improper naming of functions / variables (if you can't name it properly, you can't develop it) 2) excessive documentation where not needed (document only non-obvious stuff) 3) *complex* one-liners (because simple one-liners actually help readability) 4) and 5) can stay. :) The main point is valid though. I would phrase it like this: optimize for correctness first, readability close second, and don't optimize for performance until you can identify the significant gain (always by measuring it!).

valyard 12y ago
I don't mind improper naming because all the functions are essentially just nodes in code graph. Of course it helps if you can figure out what they do just from their names, but you have to read code anyway. Same for excessive docs. Sometimes you can find huge walls of text before every function, or meaningless javadoc comments which say that function GetData "returns data". But those are usually needed for 100% docs coverage which might be enforced by corporate policy.
- cessor 12y ago
  In a study that I did I found that bad naming makes people approximatly 15% slower. The comparison was between single name identifiers, abbreviations and "normal" words. Have a look, you might have to translate it though... http://www.cessor.de/empra13 http://www.cessor.de/empra13 Cleaned up data linked as a spreadsheet at http://www.cessor.de/antwortdaten http://www.cessor.de/antwortdaten
- deong 12y ago
  > Of course it helps if you can figure out what they do just from their names, but you have to read code anyway. This is, I think, the root of the (very minor) disagreement I have with your article. I really don't want to have to read the code anyway. There may be 250,000 lines of code in a moderately sized system. If I have to read a significant fraction of them to figure out what's going on, that's the biggest sin you as the original developer can commit by a couple of orders of magnitude. I want it to be obvious where to look for the code that controls whatever it is I want to change. If you make it easy for me to find those 50 lines of code, I don't care if you write them in assembler. 50 lines of anything are vastly easier to deal with than 250,000 (or god help you million) lines of the absolute best thing you can write.
  - valyard 12y ago
    Proper naming helps but you can't 100% trust it. bool allwaysReturnsTrue() { return false; } This is of course an extreme example (8
    - deong 12y ago
      Bad names are bad precisely because they force you to read a bunch of irrelevant code to have any hope of understanding what the code is doing. It's the same problem that over-abstracted code presents. In both cases, there's no forest I can look at -- just millions of individual trees. In a weird way though, bad names are actually better than many real-world problems. Once I find that code, I can change the name and the problem goes away. If you have a 100 line function full of one-letter variables, that's probably terrible. But I can spend a week poring over that function, figure out what they all do, and change the names. From that point, the function is fixed. I have no hope of fixing the problem with a big mess of fetishized design patterns. The confusion in many of these systems is baked into the core of the architecture in the form of a dozen layers of abstraction and indirection between me and figuring out the behavior of the system. Usually the only way to fix that is "rm -rf" and starting over from scratch.
jamesbritt 12y ago
TFA quotes Premature optimization — everything one tries to optimize before profiling and running tests on a working system. Perhaps that same thinking needs to apply to readability. Premature readability—everything one tries to improve readability before running tests. Readability seems a lot like pornography[0]; people claim to know it when they see it (or, in this case, when they don't) but are hard-pressed to offer a well-defined or objective description. What we get instead are well-meaning but subjective prescriptions. Shouldn't the alleged gains of readability practices be held to same measuring requirement as optimization? Are there solid, objective studies on what makes code more readable? In a small group it might be best to have a discussion about coding practises to achieve some consensus, but if that's not feasible then some guidelines based on research would help. 0: http://en.wikipedia.org/wiki/I_know_it_when_I_see_it http://en.wikipedia.org/wiki/I_know_it_when_I_see_it

by annnnd 12y ago

valyard 12y ago

I don't mind improper naming because all the functions are essentially just nodes in code graph. Of course it helps if you can figure out what they do just from their names, but you have to read code anyway. Same for excessive docs. Sometimes you can find huge walls of text before every function, or meaningless javadoc comments which say that function GetData "returns data". But those are usually needed for 100% docs coverage which might be enforced by corporate policy.

cessor 12y ago
In a study that I did I found that bad naming makes people approximatly 15% slower. The comparison was between single name identifiers, abbreviations and "normal" words. Have a look, you might have to translate it though... http://www.cessor.de/empra13 http://www.cessor.de/empra13 Cleaned up data linked as a spreadsheet at http://www.cessor.de/antwortdaten http://www.cessor.de/antwortdaten
deong 12y ago
> Of course it helps if you can figure out what they do just from their names, but you have to read code anyway. This is, I think, the root of the (very minor) disagreement I have with your article. I really don't want to have to read the code anyway. There may be 250,000 lines of code in a moderately sized system. If I have to read a significant fraction of them to figure out what's going on, that's the biggest sin you as the original developer can commit by a couple of orders of magnitude. I want it to be obvious where to look for the code that controls whatever it is I want to change. If you make it easy for me to find those 50 lines of code, I don't care if you write them in assembler. 50 lines of anything are vastly easier to deal with than 250,000 (or god help you million) lines of the absolute best thing you can write.
- valyard 12y ago
  Proper naming helps but you can't 100% trust it. bool allwaysReturnsTrue() { return false; } This is of course an extreme example (8
  - deong 12y ago
    Bad names are bad precisely because they force you to read a bunch of irrelevant code to have any hope of understanding what the code is doing. It's the same problem that over-abstracted code presents. In both cases, there's no forest I can look at -- just millions of individual trees. In a weird way though, bad names are actually better than many real-world problems. Once I find that code, I can change the name and the problem goes away. If you have a 100 line function full of one-letter variables, that's probably terrible. But I can spend a week poring over that function, figure out what they all do, and change the names. From that point, the function is fixed. I have no hope of fixing the problem with a big mess of fetishized design patterns. The confusion in many of these systems is baked into the core of the architecture in the form of a dozen layers of abstraction and indirection between me and figuring out the behavior of the system. Usually the only way to fix that is "rm -rf" and starting over from scratch.

jamesbritt 12y ago

TFA quotes Premature optimization — everything one tries to optimize before profiling and running tests on a working system. Perhaps that same thinking needs to apply to readability. Premature readability—everything one tries to improve readability before running tests. Readability seems a lot like pornography[0]; people claim to know it when they see it (or, in this case, when they don't) but are hard-pressed to offer a well-defined or objective description. What we get instead are well-meaning but subjective prescriptions. Shouldn't the alleged gains of readability practices be held to same measuring requirement as optimization? Are there solid, objective studies on what makes code more readable? In a small group it might be best to have a discussion about coding practises to achieve some consensus, but if that's not feasible then some guidelines based on research would help. 0: http://en.wikipedia.org/wiki/I_know_it_when_I_see_it http://en.wikipedia.org/wiki/I_know_it_when_I_see_it