57 ms·

How to write readable code? 5 Tips to improve your code readability.

27 points by wtfdeveloper 17y ago

windsurfer 17y ago
The best tip I've ever received is "Try not to write comments. Make your code speak for itself." And I write a lot of perl.
- flooha 17y ago
  Bravo if you can accomplish that with perl. I haven't hacked in perl in a long time but, from what I remember, you would have to resist using a lot of perl's shortcuts in order to make it speak for itself.
  - bigiain 17y ago
    That depends a lot on _who_ you're expecting the code to "speak" too. If I were writing code and expected non-perl programmers to read it, I might avoid using Schwartzian Transforms, but the reductio ad absurdum arguement for that point of view says you could only ever write code in plain english[1] because you might someday need it to be fixed by someone who doesn't know language-de-jour. If a Perl program needs fixing, you need to get someone who knows Perl to fix it, which means they _should_ know the standard set of Perl idioms. You _can_ write Perl in a way that Cobol programmers can easily understand and change, but you should never have too... big [1] or perhaps chinese to maximise the probability of being understood by a random maintenance programmer?
- kscaldef 17y ago
  I came here to say exactly the opposite. I read a lot of code these days where people seem to think that descriptive variable and function names replace the need for any comments. But, even the most well written code is only going to make it clear _what_ the code it doing. The _why_ is likely to remain obscure. And without knowing why the code does what it does, it will often be impossible to know whether you can make certain changes.
  - azanar 17y ago
    The _why_ is likely to remain obscure. The why might remain obscure, but that depends on two very important things: your documentation, as you noted; and your data structures. Show me your flow charts and conceal your tables and I shall continue to be mystified, show me your tables and I won't usually need your flow charts; they'll be obvious. - Fred Brooks As much as you can organize your data to make the purpose of it obvious, do that. It will make the system far easier for a new-comer to comprehend, and will make far more obvious to do you the sort of code you need to write to make the wheels turn. Where that is not enough, then use comments, but don't assume that prose is an adequate replacement for precise and logical data representation. Often times, I've found that the latter is a far better choice.
    - tetha 17y ago
      This is the reason why I am kind of laughed at, and why my comments are kind of feared, because I either don't need comments at all, but once I need comments, they usually end up being a page of things you need to know about this unit.
  - gruseom 17y ago
    You make a good point about why vs. what. Still, my experience has been that if I ask myself when adding a comment, "Could I make the code say this instead?" the answer is "yes" 9 times out of 10. It is preferable to do so because code is much likelier to be read and maintained than comments are. Also, this question often makes me see flaws in how the code was expressing itself, so I end up with better code.
    - Retric 17y ago
      I think the best comment is one which explains an ugly edge case which forces the code to look like it does. //window.update; is not used because of API bug #12345 see: bugs.mysql.com/12345 so use xyz instead. Nine times out of ten I can read and understand good code with little effort, but code often starts out looking clean and becomes messy for a reason.
- sketerpot 17y ago
  I have another version that I prefer: "Try not to write comments. Make your code speak for itself. Then comment it." Best of both worlds.
flooha 17y ago
"3.- Use abstractions only when necessary (YAGNI and KISS)...You Are Not Going to Need It (YAGNI)..." I would revise this to say "Use abstractions only when you can see a valid future use." I've spent days and weeks literally just thinking about how to architect a solution and wrapping my mind around all the possibilities. Months later, after making those decisions and writing the code, I inevitably need to add new functionality. Often, I can accomplish my new goal with a ridiculously small amount of code and it really gives me joy for the rest of the day. I could have taken the easy route initially and just done "what was necessary", but I would have paid for it ten fold later...and sometimes do when I take the shortcut (which is thankfully rare.)
- akeefer 17y ago
  The flip side of that question, though, is how often you add in abstractions that you either never use or to code that you don't really need to change. Planning for the future, as it were, is only a win if the amount of time you save when you guess right is larger than the amount of time you pay when you guess wrong and do unnecessary work (or make things more complicated than necessary, thus slowing down all related work, etc.). I'm all for properly refactoring code, but there's something to be said for the fact that trying to guess what you'll need in the future usually equals guessing wrong, unless "the future" is really close in time (i.e. a week or two away). Personally I've had plenty of those "glad I abstracted it this way" or even "I wish I'd abstracted it initially" moments, but also plenty of the "wow, good thing I didn't sink too much time into this 4 months ago because I would have never guessed I'd need to change it this way" moments too.
- nostrademons 17y ago
  I'd restrict that further. "Use abstractions only when you can see a valid present use." I've also spent days and weeks thinking about how to architect a solution, and then been wonderfully gratified when I can add new functionality with just a couple lines. More often, however, I find that the new function ends up being something totally unexpected, which I would never have thought of at the time I was writing the code. And then I have to throw away all those carefully crafted abstractions, because they just get in the way and slow me down while the software changes in unexpected ways. It's easy to remember the successes. But more often, initial overarchitecting just results in lost time and wasted effort. Worse, it can be actively counterproductive if you don't have the courage to throw away dead code that's no longer useful.
bodhi 17y ago
if it takes more than 5 minutes for the other programmer to have a high level idea of the design, assume that the code is not readable. I'd argue that a high-level description of the system being easy to grasp is kind-of orthogonal to whether the code is readable or not.
- ricree 17y ago
  Perhaps, but I'm guessing that what he means here is more of a rough structural understanding of the code. In other words, what pieces have what function, and in general how do they interact with one another. While this doesn't necessarily mean the code will be readable, I'd say that there's a lot to be said for a code layout in which it's easy to figure out roughly which code needs to be touched to make a given change or fix.
alexgartrell 17y ago
Be brief. When their are three ways to do something, do the one that takes the least code (assuming it's not completely obscure and ridiculous). It's analogous to talking to people: the more you say the less they remember.
- samuel 17y ago
  I agree. I prefer to attach a 5-line comment to 10 lines of code to writing 15 lines of code. If the reader knows the idiom great, if not, he can grasp it without going into the details. Not everybody agrees, though.

27 points by wtfdeveloper 17y ago

The best tip I've ever received is "Try not to write comments. Make your code speak for itself." And I write a lot of perl.

flooha 17y ago
Bravo if you can accomplish that with perl. I haven't hacked in perl in a long time but, from what I remember, you would have to resist using a lot of perl's shortcuts in order to make it speak for itself.
- bigiain 17y ago
  That depends a lot on _who_ you're expecting the code to "speak" too. If I were writing code and expected non-perl programmers to read it, I might avoid using Schwartzian Transforms, but the reductio ad absurdum arguement for that point of view says you could only ever write code in plain english[1] because you might someday need it to be fixed by someone who doesn't know language-de-jour. If a Perl program needs fixing, you need to get someone who knows Perl to fix it, which means they _should_ know the standard set of Perl idioms. You _can_ write Perl in a way that Cobol programmers can easily understand and change, but you should never have too... big [1] or perhaps chinese to maximise the probability of being understood by a random maintenance programmer?
kscaldef 17y ago
I came here to say exactly the opposite. I read a lot of code these days where people seem to think that descriptive variable and function names replace the need for any comments. But, even the most well written code is only going to make it clear _what_ the code it doing. The _why_ is likely to remain obscure. And without knowing why the code does what it does, it will often be impossible to know whether you can make certain changes.
- azanar 17y ago
  The _why_ is likely to remain obscure. The why might remain obscure, but that depends on two very important things: your documentation, as you noted; and your data structures. Show me your flow charts and conceal your tables and I shall continue to be mystified, show me your tables and I won't usually need your flow charts; they'll be obvious. - Fred Brooks As much as you can organize your data to make the purpose of it obvious, do that. It will make the system far easier for a new-comer to comprehend, and will make far more obvious to do you the sort of code you need to write to make the wheels turn. Where that is not enough, then use comments, but don't assume that prose is an adequate replacement for precise and logical data representation. Often times, I've found that the latter is a far better choice.
  - tetha 17y ago
    This is the reason why I am kind of laughed at, and why my comments are kind of feared, because I either don't need comments at all, but once I need comments, they usually end up being a page of things you need to know about this unit.
- gruseom 17y ago
  You make a good point about why vs. what. Still, my experience has been that if I ask myself when adding a comment, "Could I make the code say this instead?" the answer is "yes" 9 times out of 10. It is preferable to do so because code is much likelier to be read and maintained than comments are. Also, this question often makes me see flaws in how the code was expressing itself, so I end up with better code.
  - Retric 17y ago
    I think the best comment is one which explains an ugly edge case which forces the code to look like it does. //window.update; is not used because of API bug #12345 see: bugs.mysql.com/12345 so use xyz instead. Nine times out of ten I can read and understand good code with little effort, but code often starts out looking clean and becomes messy for a reason.
sketerpot 17y ago
I have another version that I prefer: "Try not to write comments. Make your code speak for itself. Then comment it." Best of both worlds.

flooha 17y ago

"3.- Use abstractions only when necessary (YAGNI and KISS)...You Are Not Going to Need It (YAGNI)..." I would revise this to say "Use abstractions only when you can see a valid future use." I've spent days and weeks literally just thinking about how to architect a solution and wrapping my mind around all the possibilities. Months later, after making those decisions and writing the code, I inevitably need to add new functionality. Often, I can accomplish my new goal with a ridiculously small amount of code and it really gives me joy for the rest of the day. I could have taken the easy route initially and just done "what was necessary", but I would have paid for it ten fold later...and sometimes do when I take the shortcut (which is thankfully rare.)

akeefer 17y ago
The flip side of that question, though, is how often you add in abstractions that you either never use or to code that you don't really need to change. Planning for the future, as it were, is only a win if the amount of time you save when you guess right is larger than the amount of time you pay when you guess wrong and do unnecessary work (or make things more complicated than necessary, thus slowing down all related work, etc.). I'm all for properly refactoring code, but there's something to be said for the fact that trying to guess what you'll need in the future usually equals guessing wrong, unless "the future" is really close in time (i.e. a week or two away). Personally I've had plenty of those "glad I abstracted it this way" or even "I wish I'd abstracted it initially" moments, but also plenty of the "wow, good thing I didn't sink too much time into this 4 months ago because I would have never guessed I'd need to change it this way" moments too.
nostrademons 17y ago
I'd restrict that further. "Use abstractions only when you can see a valid present use." I've also spent days and weeks thinking about how to architect a solution, and then been wonderfully gratified when I can add new functionality with just a couple lines. More often, however, I find that the new function ends up being something totally unexpected, which I would never have thought of at the time I was writing the code. And then I have to throw away all those carefully crafted abstractions, because they just get in the way and slow me down while the software changes in unexpected ways. It's easy to remember the successes. But more often, initial overarchitecting just results in lost time and wasted effort. Worse, it can be actively counterproductive if you don't have the courage to throw away dead code that's no longer useful.

bodhi 17y ago

if it takes more than 5 minutes for the other programmer to have a high level idea of the design, assume that the code is not readable. I'd argue that a high-level description of the system being easy to grasp is kind-of orthogonal to whether the code is readable or not.

ricree 17y ago
Perhaps, but I'm guessing that what he means here is more of a rough structural understanding of the code. In other words, what pieces have what function, and in general how do they interact with one another. While this doesn't necessarily mean the code will be readable, I'd say that there's a lot to be said for a code layout in which it's easy to figure out roughly which code needs to be touched to make a given change or fix.

alexgartrell 17y ago

Be brief. When their are three ways to do something, do the one that takes the least code (assuming it's not completely obscure and ridiculous). It's analogous to talking to people: the more you say the less they remember.

samuel 17y ago
I agree. I prefer to attach a 5-line comment to 10 lines of code to writing 15 lines of code. If the reader knows the idiom great, if not, he can grasp it without going into the details. Not everybody agrees, though.