Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Boost Maintainability

Boost Maintainability

In your codebase, to understand a random line, how many lines do you need to read back? Cloud you make it zero?

This talk will start with the impact of the maintainability, define the maintainability as “to understand a random line, the lines you need to read back”, show the practical techniques to make it zero, or nearly zero, and finally, reach the goal: boost the maintainability.

It's the revision of “Beyond the Style Guides” [1] and the talk at PyCon TW 2016 [2], PyCon APAC/KR 2016 [3], and GDG DevFest Taipei 2016 [4].

[1]: https://speakerdeck.com/mosky/beyond-the-style-guides
[2]: https://tw.pycon.org/2016
[3]: https://www.pycon.kr/2016apac/
[4]: https://devfest-taipei-3cbee.firebaseapp.com/

Mosky Liu

June 03, 2016
Tweet

More Decks by Mosky Liu

Other Decks in Programming

Transcript

  1. —Joel on Software Making Wrong Code Look Wrong • “Making

    Wrong Code Look Wrong” • http://bit.ly/joel-wrong • This talk will be more systemic than it. • But exception is good, IMO.
  2. ❤ Python & Open Source Mosky • Backend Lead at

    Pinkoi. • Has spoken at: • PyCons in TW, JP, SG, HK, KR, MY, COSCUPs, and TEDx, etc. • Countless hours on teaching Python. • Own Python packages: • ZIPCodeTW, MoSQL, Clime, etc. • http://mosky.tw/
  3. The General Rules Ops Clues • Clue the ops you

    should use. • _no: numeric. • <plural>: sequence, usually is mutable sequence (list). • _<type>: if no intuitive way. • _<abstract type>: • _seq: for sequence. • _gen: for generator. • More: collections.abc – Python Docs.
  4. For Callable Ops Clues • <verb>_ = imperative sentence. •

    <yes-no question> → boolean. • to_<thing> → thing. • from_<thing> ← thing.
  5. For Boolean Ops Clues • The normal objects took the

    nouns. • The callables took <verb>_ and <yes-no question>. • We have: • <preposition>_ • <simple sentence> • to_<verb>_ • <adj>
  6. For Return Value Ops Clues • Clue the return value:

    • get_page_no → numeric which >= 1. • query_user → user object. • parse_to_tree → tree object.
  7. Avoid None and Null Ops Clues • Consider: • user

    = query_user(uid) user.is_valid() • Then query_user returns None. • Boom! An AttributeError! ∵ None supports almost no op. • Accept an exception? • Y: Just raise when you wanna return None. • N: Use a dummy object like a dummy user or an empty str, etc.
  8. str/x Ops Clues • _key: str/key (of a dict). •

    'lowercase_n_underscore' • _json: str/json. • JSON is a string, not dict. • _url: str/url. • Clue percent-encoding; avoid URL injection. • _html: str/html. • Avoid XSS. • _sql: str/sql. • Avoid SQL injection.
  9. numeric/x Ops Clues • _no: number, #. • ≥ 1.

    • _idx: index. • ≥ 0. • Or just i, j, k. • _secs • It's seconds! • _pct • n = 10% n_pct = 10 • _month, _day, ... • Use month_str if in string.
  10. For Dict & Tuple Structure Clues • <key>_<value>_dict • For

    tuples: • _pair: 2-tuple. • _pairs: 2-tuples. • <1st>_<2nd>_<3rd>_tuple: n-tuple.
  11. “Don't use me!” • _<name> • Don't use when out

    of: • A module. • A class. • Don't guarantee the behavior. • Make it easier to trace and refactor. Private Clues
  12. “Should I cache it?” Performance Clues • get_ / set_:

    memory op. • parse_ / calc_ : CPU-bound op. • query_: IO-bound op. • query_or_get_: IO-bound op with cache.
  13. With Blank Line and Comment Paragraph & Section • Like

    writing in Markdown. • Paragraph: • A paragraph contains no blank line. • A blank line separates paragraphs. • Section: • A section contains paragraphs. • A comment with blank line separates sections.
  14. By Calls Line Functions Up • Measure the “orderliness”. •

    Keep them have the same direction. • May become module. • Try to line the classes and modules up by the imports?
  15. Don't get lost! Face Bad Smell • Comment: • For

    the pitfalls, the actual return type, the side effects, etc. • Use # FIXME: ... or # XXX: ... . • Seal it: • good = poor() • def good(): poor() • Stay focused!
  16. Photo Credits • “The Money“ https://commons.wikimedia.org/wiki/ File:Forex_Money_for_Exchange_in_Currency_Bank.jpg • “The Bricks”

    https://pixabay.com/zh/%E5%BB%BA%E8%AE%BE- %E6%92%AD%E6%94%BE-%E7%8E%A9%E8%80%8D- %E4%B9%90%E8%B6%A3-%E5%88%9B%E6%84%8F-1159776/ • Thanks!