

How to write readable code? 5 Tips to improve your code readability. - wtfdeveloper
http://www.makinggoodsoftware.com/2009/06/22/how-to-write-readable-code/

======
windsurfer
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.

~~~
kscaldef
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.

~~~
gruseom
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
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.

------
flooha
"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.)

~~~
nostrademons
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.

~~~
tetha
In fact, even at the danger of being annoying, I would rephrase that once
again. "USE abstractions when you can see a valid present use". Not listening
to your code asking for a common abstraction of several things which already
exist just for the sake of not using an abstraction ("well, because!") will
result in an even bigger mess than most abstractions cause.

------
bodhi
_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
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
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
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.

