

Five Rules for Writing Good Code - biotech
http://skwpspace.com/2009/09/29/five-rules-for-writing-good-code/

======
aditya
_If we see lots of comments interspersed in a method, it is a good sign that
the code cannot be easily understood. Break it down into lots of little
functions with descriptive names, and all of a sudden our code reads like a
very clear and concise recipe, and we find that the comments become redundant.
Most comments that live inside functions are parasitic organisms, treat them
with suspicion._

Seriously? I've seen this a lot in the Ruby world and it works in a lot of
cases but using it as a rule sounds Wrong.

~~~
dbz
When I am commenting (for someone else) I always stick at least one comment in
(or above the function) per function, that way everything is clear, even if
the comment is describing where the function will be used. That rule is awful
imho.

------
city41
Refactoring large methods into a collection of small aptly named ones has its
drawbacks too. When reading the code the reader has to keep a mental stack
going maintaining what each sub function means/does. Sometimes this is worse
than keeping it inline. There is definitely a good balance to be had between
the two approaches.

~~~
aerique
You shouldn't need to keep a mental stack since as you say the small functions
are aptly named. You just check once whether the function really does what it
suggests and then you don't have to throw it on your stack the next time.

~~~
InclinedPlane
Exactly. Naming and proper design is very important. Tracking state changes
through numerous "DoStuff" and "HandleThings" methods definitely represents
additional intellectual overhead.

------
keefe
I think these are all very good ideals to strive towards. However, the real
world often doesn't work that way - there is some pressing "business deadline"
that you simply cannot avoid hustling to meet. That's why I would prefer
writing for a purpose to writing for an audience. That's why his second point
is so important - this relates directly to defining the proper interfaces for
your code! If your interfaces are all beautiful, you can take an iterative
approach to the implementations if there is time pressure. Crank something out
that works, put out the fire and then rewrite it afterwards. I've always found
that in all times of writing, multiple rewrites are a key technique.

------
diN0bot
1\. and 2. are spot-on. i treat many of my projects as collaborative open
source projects before i even have collaborators. the weekend netflix api wars
are total hacks, but anything complicated and persistent is so much better if
i take the long view. it then becomes something i am proud of and want to
continue working on, rather than something confusing and limited.

the last three points don't resonate with me strongly either way, though i
will say that 5. is awesome to achieve, and is definitely helped via a
persistent and open spirit rather than single-person hacking.

