How to improve your coding style and documentation with python programming language?
The main goal of a programmer/ developer is to write a code which is easily understandable by anyone who read them. Good programmers should therefore be mindful of their coding style, and develop a style that communicates the important aspects of a program’s design for both humans and computers. Conventions for coding style tend to vary between different programming communities. In python programming language various types of rules are adopted to do so:
Indentation and spaces
We typically indent a block with 4 spaces or a tab space. In order to avoid having our code fragments overrun the book’s margins, we use 2 spaces for each level of indentation. Lately, use of tab spaces is avoided as tabs are displayed with differing widths across systems, and tabs and spaces are not viewed as identical by the Python interpreter. Code editors are like Visual Studio replaces the tabs to spaces automatically.
Use of Identifiers
Names of identifiers must be chosen in such a way that it reflects the action that it is supposed to, responsibility, or data each identifier is naming.
a). Classes should utilise “CamelCase” approach. When multiple words are concatenated to form a class name like a singular noun as if we define a class that calculate the eligibility of the credit card then we can use class name as CreditCard.
b). Functions, including member functions of a class, should be lowercase. If multiple words are combined, they should be separated by underscores (e.g., make payment). The name of a function should typically be a verb that describes its affect. But if the function just returns a value then function name could be a noun describing its value(e.g., sqr rather than calculate_square)
c). Names that identify an individual object (e.g., a parameter, instance variable, or local variable) should be a lowercase noun (e.g., price). Occasionally, we stray from this rule when using a single uppercase letter to designate the name of a data structures (such as tree T).
d). Identifiers that represent a value considered to be a constant are traditionally identified using all capital letters and with underscores to separate words (e.g., MAX_SIZE).
e). Identifiers in any context that begin with a single leading underscore (e.g., _secret) are intended to suggest that they are only for “internal” use to a class or module, and not part of a public interface.
Using Comments
This is by far most important thing that needs to be done if you want to improve your coding style. Comments can add meaning to a program and explain ambiguous or confusing constructs. In-line comments are good for quick explanations; they are indicated in Python following the # character, like:
if n % 2 != 1: # n is evenWe also use multiline comments which can be used to explain hard to explain type of code block. In Python, these are technically multiline string literals, typically delimited with triple quotes (”” ”), which have no effect when executed.
DOCUMENTATION — Python provides integrated support for embedding formal documentation directly in source code using a mechanism known as a docstring. Formally, any string literal that appears as the first statement within the body of a module, class, or function (including a member function of a class) will be considered to be a docstring.
Formally, any string literal that appears as the first statement within the body of a module, class, or function (including a member function of a class) will be considered to be a docstring. By convention, those string literals should be delimited within triple quotes (”””). The following function
def scale(data, factor):
”””Multiply all entries of list by the given factor.”””
for j in range(len(data)):
data[j] = factorIt is common to use the triple-quoted string delimiter for a docstring, even when the string fits on a single line. More detailed docstrings should begin with a single line that summarizes the purpose, followed by a blank line, and then further details.
A docstring is stored as a field of the module, function, or class in which it is declared. It serves as documentation and can be retrieved in a variety of ways. For example, the command help(x), within the Python interpreter, produces the documentation associated with the identified object x. An external tool named pydoc is distributed with Python and can be used to generate formal documentation as text or as a Web page.
