202304281141-clean_code
Stakeholders
It may sometimes be hard to convince the business that it's worth investing time in clean code, but ultimately this benefits many stakeholders. First of all, clean code makes it easier for colleagues but also your future self to adapt and build forth on the code base. This in turn is beneficial for the speed and quality of development, which impacts other teams waiting on your code changes. Secondly, depending on the company and domain, code being optimized can directly impact customer experience (e.g. load times on a website) and should be important for any stakeholder invested in the succes of the company.
Clean code is readable, simple, and concise.
When to use?
Clean code principles should be applied...
- In production settings
- When sharing code with others
- When code will be re-used
Requirements:
- Maintainability
- Dependability
- Efficiency
- Usability
Clean code is always useful, but implementing best practices costs more time than writing code for some ad-hoc analysis, it may not be necessary.
Clean code and collaboration
Git and Github have been pivotal tools for clean code. Because they allow people around the world to share code and collaborate, the following of clean code principles is a major factor in the succes of open source projects. Open source projects have a better chance to thrive if they follow clean code principles because it makes it easier for people to contribute.
Naming conventions
Informative naming conventions improve readability and take away the need to provide additional inline comments.
Not s = [87, 25, 58] # student test scores but test_scores = [87, 25, 58].
- Imply type
- E.g. imply the type is a boolean by prefixing a variable name with
is_orhas_ - Use parts of speech that indicate the action a function takes, e.g.
categorize_task(*args)instead ofcategory(*args).
- E.g. imply the type is a boolean by prefixing a variable name with
- Be consistent but focus on differentiation
- If we have an
ageand a list calledages, the difference is more explicit withage_list - Personally, I actually dislike
age_listand find it too verbose; I'd use explicit typing in this case:ages: list = [1, 2, 3]
- If we have an
- Avoid abbreviations and single letter variables, with the exception of counters, common math variables, and common conventions, such as importing numpy as
np. - Making a descriptive name does not equal making a long name
- E.g. a function name should describe what the function does, but should not mention implementation detail.
- Have correct and consistent use white spaces
- Organize logical blocks / sections with empty lines
- Maintain max line length
- Standard in Python: four spaces.
- Different naming conventions may be appropriate for other languages and libraries
- E.g. don't use spaces in column names of pandas dataframes so you can use dot notation for selecting columns.
Modular code
- DRY: don't repeat yourself
- Abstract out logic in functions is less repetitive, but also more readable if descriptive function names are used.
- But avoid over-engineering
- Minimize the number of entities: having more modules does not necessarily lead to effective modularization
- Watch this trade-off and avoid that you have to jump through many calls to make simple changes.
- Functions should do one thing; avoid unnecessary side-effects
- This can be as trivial as printing some additional computation in a function doing another computation
- Consider refactoring if you can place the word "and" in your function name
- Sometimes it's actually better to use arbitrary variable names
- E.g. if you write a function that does an operation on any type of numpy array, it facilitates reuse of your function if you name the parameter very generic
arr.
- E.g. if you write a function that does an operation on any type of numpy array, it facilitates reuse of your function if you name the parameter very generic
- Try to use fewer than three arguments per function is possible