Five Rules for Writing Good Code | Hacker News Reader

Five Rules for Writing Good Code

skwpspace.com

30 pointsbiotech10 comments

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.

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.

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.

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.

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

A better title for the article might have been "Five Heuristics for Writing Good Code".

I think that if you follow the "One level of abstraction per function" tip from the "Clean Code" book, and you do a proper naming of your functions this problem disappears.

I actually have a blog post about this general subject: http://jasonmbaker.com/the-devils-in-the-details

In extracting code into a method, you're intentionally obscuring what it does. Most of the time this is a good thing because you want to only focus on the details of the routine you're in. Thus, if you follow the "make your method do one thing" rule, you should be ok.

If your methods have no cohesion to them, then you will have problems breaking them down. But then again, I would argue that that's the least of your problems.

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.

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.

Reply on news.ycombinator.com