Hacker News Reader

Comment by Game_Ender | Hacker News Reader

Do you have any more details on your recommendations?

Get variable and method/function names right. They matter more than most comments. I remember a code base I inherited

    if avail > 0:

I could never reason well about that. Then I changed it to

    if available_hosts > 0:

and eventually into

    if number_of_hosts_to_scan > 0:

Technically this would be enough

    if number_of_hosts_to_scan:

but it's less clear.

I'm not afraid to type long variable names because the editor has autocomplete. I don't type much and I don't make typos.

If the function is called scan_hosts, then if the parameter is n, it's more or less obvious to me that n it's number of hosts to scan. I'm willing to read a block comment to remind me what n is.

Some issues could be:

1. It is not obvious to everyone. 2. Another integral parameter called k is added later on. Now which is which? 3. Another guy might call all his integral parameters k. n and k are used for the same thing all over the code-base. An outsider might initially think they are different. 4. Names which are descriptive of their use are obvious to everyone by definition.

It may not be obvious to strictly everyone, but that should be reasonably obvious to anyone with enough context to have any business touching that code.

nHosts according to a popular naming standard and using camel case.

At least one of them will be something similar to: write boring code. Document just a little more than you think you need to (be that in self-descriptive variables or actual comments). Don't get fancy unless actual measured performance dictates it, and when you do so, make sure you document both the why (which test indicated this was necessary) and the how (this is what we did, exactly, to make it perform better).

Write code like you’ll have to debug it at 2 am. Some day you will.

Uncle Bob’s Clean Code.

Reply on news.ycombinator.com