5 ms·

Do you have any more details on your recommendations?

mjevans 8y ago
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).
pmontra 8y ago
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.
- kazinator 8y ago
  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.
  - pauljurczak 8y ago
    nHosts according to a popular naming standard and using camel case.
  - 0db532a0 8y ago
    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.
    - yellowapple 8y ago
      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.
0db532a0 8y ago
Uncle Bob’s Clean Code.
hinkley 8y ago
Write code like you’ll have to debug it at 2 am. Some day you will.

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

pmontra 8y ago

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.

kazinator 8y ago
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.
- pauljurczak 8y ago
  nHosts according to a popular naming standard and using camel case.
- 0db532a0 8y ago
  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.
  - yellowapple 8y ago
    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.

0db532a0 8y ago

Uncle Bob’s Clean Code.

hinkley 8y ago

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