An engineer spends a substantial amount of time reading code, maybe more than actually writing it. So an emphasis on readability of that code is critical. Some programming languages offer official style guides to enforce good readability principles.
But why do style guides matter? Style guides contain best practices for writing and maintaining code. These style guides are written by experienced engineers who have written and maintained a lot of code. For example, Python’s style guide’s main author is Python’s creator, Guido Van Rossum. These engineers know what works and what doesn’t. Style guides teach us how to write maintainable code based on principles of standardisation and consistency.
Standardization and consistency in design result in efficiencies. Imagine if you’ve to follow different traffic signs in different cities or different traffic signs in the same city? Life would be difficult if that were the case.
Sometimes, these style guides help avoid unnecessary debates as well.
A lot of companies publish open-source on Github. Many people love reading their code because that’s one good way to learn how to write better code. So obviously big companies have a great responsibility to put well-written, polished code on the Internet that adheres to language style guidelines. Most of the time that responsibility is fulfilled.
I recently saw some open-source Python code by Google which is available here https://github.com/googleads. Kindly note that I’m not an expert Python programmer and the purpose of this post isn’t by any means to undermine Google’s Python contribution in the open-source world. Google undoubtedly has contributed lot of wonderful open-source Python code. Just an observation that I thought worth sharing.
I had to look at a few Google Ad libraries to learn about a couple things, and I came across this library: https://github.com/googleads/googleads-ssr-generator. I downloaded the code and opened it up in the source-code editor.
The main file looks simple in that it’s roughly 230 lines with most of the code defined in methods. I, however, was not able to run the code on a Mac given the instructions in the README file. What surprised me most is the fact that the code is not PEP-8 (Python’s official style guide)-compliant. More importantly, it also isn’t compliant to Google’s own Python style guide. For example, one can find method names such as :
Whereas as per PEP-8 method names should be:
“lowercase with words separated by underscores as necessary to improve readability.”
Google’s Python style guide also suggests similar rule for method names.
Moreover, the source-code doesn’t adhere to a 4-space indent as suggested by both Google’s Python style guide and PEP-8 guidelines.
I think the code should be defensive, designed to prevent bugs. Methods should be written in a way that they are very conservative about the parameters they will accept, but very liberal in returning variables from the methods. Some parameter-checking would have been nice in this repository.
It’s also a good idea to use constants in the code since that makes future changes easy. For example, in the following snippet (taken from Google’s repository), the second, third and last parameters could have been defined as constants in a constant file.
service, _ = sample_tools.init(argv, ‘adexchangebuyer’, ‘v1.3’, __doc__, __file__, parents=[argparser], scope=’https://www.googleapis.com/auth/adexchange.buyer')
Also, a requirements.txt file would have definitely helped in the code repository.
The code comes with unit tests. However, it would have been nice if the tests had used something like unittest or Pytest.
I’m assuming these changes wouldn’t have required a lot of time. Rules in style guides can be broken as long as they are backed by sound judgement. Written code that adheres to language-style guidelines can be really helpful for a lot of people.