It is useful to indicate in the documentation that the semantic meaning is "seconds", thus 5.0 means 5 seconds. That is, in the example above, there is no need to say timeout is a float, because the default value is 5.0, which is clearly a float. Good_names + explicit_defaults > verbose_docs + type_specs Short docstrings are proper one-line sentences But notice how Tornado did not go overboard: there is one exception class for all HTTP errors raised by the framework or user code.
A good example of an exception type that clearly had to exist is. If so, you probably should make your own type. It is most common to raise ValueError (bad argument), LookupError (bad key), or AssertionError (via the assert statement) in user code.Ī good rule of thumb for whether you should create your own exception type is to figure out whether a caller should catch it every time they call your function. Leverage these appropriately, and you should "customize" them simply by instantiating them with string messages that describe the specific error condition you hit. Note that Python includes a rich set of built-in exception classes. # good raise ValueError( "bad value for url: %s" % url) PEP8 suggests using a trailing underscore to avoid aliasing a built-in, e.g. Functions and methods can have a _prefix notation to indicate "private", but this should be used sparingly and only for APIs that are expected to be widely used, and where the _private indicator assists with information hiding. Notice that Python names True, False, and None use CamelCase even though they are not classes. You can also choose to use CamelCase for things that are class-like but not quite classes - the main benefit of CamelCase is calling attention to something as a "global noun", rather than a local label or a verb. You should generally follow these rules, unless you are mirroring some other tool's naming convention, like a database schema or message format. Precompiled regular expressions: name_re.(But, prefer names that don't need underscores!) Method and function names: lower_with_underscores.Variable names: lower_with_underscores.Class names: CamelCase, and capitalize acronyms: HTTPWriter, not HttpWriter.Many of these were adapted from the Pocoo team. On naming, following some simple rules can prevent a whole lot of team-wide grief. If you find a function where all the lines are longer than this, something else is wrong, and you should look at your code rather than at your flake8 settings. Note also that often a # noqa comment can be added to a line to have a flake8 check ignored, but please use these sparingly.ĩ0%+ of your lines should be 79 characters or fewer, though, for the simple reason that "Flat is better than nested". Here's the link to flake8 config, see the max-line-length config option. It's probably still a good rule-of-thumb - like a "rule" that says English sentences should have 50 or fewer words, or that paragraphs should have fewer than 10 sentences. If the strict 79-character line length rule in flake8 bothers you, feel free to ignore or adjust that rule. The only set of rules that seem to cause a disproportionate amount of controversy are around the line length and naming. Make sure to read the section of PEP8 that is titled: "A Foolish Consistency is the Hobgoblin of Little Minds." Also see Raymond Hettinger's excellent talk, "Beyond PEP8" for more on this. PEP8 is meant as a set of guidelines, not rules to be strictly, or religiously, followed. The best tool to enforce these rules, while also helping you catch silly Python syntax errors, is flake8. PEP8 covers lots of mundane stuff like whitespace, line breaks between functions/classes/methods, imports, and warning against use of deprecated functionality. but, be flexible on naming and line length. I hope it can be a kind of condensed "Strunk & White" for Python code.
It goes beyond mere issues of syntax and module layout, and into areas of paradigm, organization, and architecture. It is opinionated, but not too opinionated. This document goes beyond PEP8 to cover the core of what I think of as great Python style.
0 kommentar(er)
