Skip to content

Good coding practice

Good coding practices are a very vast topic ranging from computer science concepts such as using adequate programming design patterns to following code naming conventions, but also writing clear commit messages, commenting code, documenting how to replicate your programming setup, writing informative tests, and much more. What these "good" practices have in common, is that they allow developers to be more efficient at programming: consistent formatting helps spot errors, good documentation speeds up maintenance and refactoring, good design allows to easily add new features, etc. Consistently following good practices will help others to engage with your code, but also help you with your own code when re-visiting it after a while!

Good practices will be distilled throughout the entire school, about every subject that is presented. However, since the S3 School is not a python programming school, we don't have the time to go in details into python programming good practices. Let's use this lecture to do a little reminder nonetheless, it can never hurt!

Generic good coding practices

There are a number of "good coding practices" that can be followed independently of the programming language or application:

  1. Keep it small and simple.
    Any isolated part of a program (a function, a method, a class, a module) "should do one thing. They should do it well. They should do it only". p 35 in Robert C. Martin, Clean Code, Pearson 2009.
    See also The Unix philosophy emphasizes building simple, compact, clear, modular, and extensible code
  2. Don't repeat yourself. (DRY principle)
    "Every piece of knowledge must have a single, unambiguous, authoritative representation within a system" Hunt, Andrew; Thomas, David (1999). The Pragmatic Programmer: From Journeyman to Master
  3. Define interfaces first.
    Precisely laid out interfaces allow collaborators to work more independently, therefore more efficiently.
  4. Don't use global variables.
    It's a bad idea, as you will discover if you try to unit test it or parallelize it.
  5. Don't use hard-coded values.
    Hard-coded values are simply hard to refactor automatically. Default values seem nice for a while, until their value is not suited anymore: then you are either stuck with a poor default value, or you must change it and risk breaking someones code.
  6. Give variables, function and classes descriptive names.
    It improves code readability tremendously: it's like free documentation.
  7. Follow a consistent formatting convention
    For instance python general convention is snake case for variables and functions, StudlyCaps (PascalCase) for Classes.
  8. Document everything.
    Write the documentation as you code. You'll thank yourself in a few months, or someone else will!
  9. Feel the vibes.
    AI assistant can be great, but you are responsible for what the code you implement does, don't forget to validate it.

These very generic rules give us a starting point to improve the readability of the pkoffee implementation:

  • implement abstractions instead of defining objects directly in the global scope main.py
  • remove all hardcoded values (column names, plot parameters, models attributes, ...)
  • use explicit names for variables
  • apply formatting convention

Zen of python

Tim Peters, one of the main contributor to the python language, wrote a set of 19 principles to guide python program writing named the zen of python:

  • Beautiful is better than ugly.
  • Explicit is better than implicit.
  • Simple is better than complex.
  • Complex is better than complicated.
  • Flat is better than nested.
  • Sparse is better than dense.
  • Readability counts.
  • Special cases aren't special enough to break the rules.
  • Although practicality beats purity.
  • Errors should never pass silently.
  • Unless explicitly silenced.
  • In the face of ambiguity, refuse the temptation to guess.
  • There should be one-- and preferably only one --obvious way to do it.
  • Although that way may not be obvious at first unless you're Dutch.
  • Now is better than never.
  • Although never is often better than right now.
  • If the implementation is hard to explain, it's a bad idea.
  • If the implementation is easy to explain, it may be a good idea.
  • Namespaces are one honking great idea – let's do more of those!

While the first 7 principles are rather explicit, one can imagine that they sometimes conflict with one another. How to chose a path in this case? The principles that work in pairs can be either more puzzling at first as they leave room for exceptions to their own rules. How to recognize the special cases when making an exception to the rule is justified, and the cases when it is not worth the trouble?
With experience one forges an opinion and will become more confident to judge. In some cases though, there may not be a definitive answer! As the word zen implies, these principles are not set-in-stone rules to follow blindly, one should pounder each affirmation when considering a difficult implementation decision. A best practice hidden between the lines of the zen principles is that thinking and arguing about code helps reveal flaws and benefits and make us improve as developers!

Conclusion

Experience has shown that in the long run, following good practices increases productivity and quality, that's why they are considered good practices!