Some coding recommendation guidelines for scientifc programming with Python

guidelines.MD

"Rules are to make you think before you break them." – Terry Pratchett

Some guidelines to follow for coding to increase collaboration efficiency.

• Name variables meaningfully.
  • It pays of to think hard about it, because coming up with names is O(1) while trying to decipher names is O(“amount of people that try to understand the code”).
  • Don’t be afraid of long variable names; it is much better to have a long obvious name than a short name that does not “flow” while reading code.
  • Avoid greek letter names such as epsilon, eta or gamma. The right variable names are often offset, step_rate or decay_factor. Even if the paper you are implementing is using certain greek names, a follow up won’t. Also, mathematical formulas in papers and source code are different things with different objectives.
  • Sometimes it makes sense to “meaning type” of variables in their names, even more so in dynamically typed languages such as Python. E.g., if you want to express that a variable holds a count of buckets, n_buckets is better than buckets–the latter hold the buckets themselves. Here, n stands for “number of”.
• Adhere to everything of pep8 If this feels like a big pain, there are editor extensions that mark lines for you that break the style. It really helps learning.
• Use
  • lower_case_with_underscore for methods, functions, variables,
  • lowercase for modules and packages,
  • CamelCase for classes,
  • UPPER_CASE_WITH_UNDERSCORES for constants.
• Use the numpy documentation guidelines when writing doc strings.
• Use sklearn’s guidelines on
  • Input validation
  • Random numbers
• Some more input
  • Brandon Rhodes slides on programming style
  • Kevin Henney's talk on progamming style