222.html

Python Ebook Python&XML

var = (x+y * (w/z))

					</PRe>

					<p>The previous expression resembles <tt CLASs="monofont">((x+y) * (w/z))</tt> when in fact it is  <tt class="monofont">(x+(y * (w/z))).</tt> A good way to write that would be</p>

					<pre>
						
var = (x + y*(w/z))

					</pre>

				
				
					<h4>


Comments</H4>
					<p>If you decide to add comments to your code, you need to remember to keep them up-to-date all the time. Otherwise, it can become more of a problem than being a helper thing. Some of the basic rules for writing comments are listed next:</p>

					<Ul>
<li>
							<P>Write your comments in plain English. For large projects with members of different nationalities, English is often the common language. Of course, if no developers know English, this rule is not a good idea.</p>

						</li>
<lI>
							<p>Capitalize the first word of sentences and phrases.</p>

						</lI>
<LI>
							<P>Omit the period at the end of short comments.</p>

						</li>
<lI>
							<P>Never alter the case of identifiers. Remember that Python is case sensitive; thus, you should write your helper comments using the same notation used by the definition of the object that you are describing.</P>

						</Li>
</ul>
					<p>There are two kinds of comments: block comments and inline comments. The former applies to the code that follows it, and the latter is put on the code's own line. Both types require at least a single <A NAMe="idx1073749518"></a>
						<a nAME="idx1073749519"></A>
						<tt class="monofont">#,</tt> followed by a single space at the beginning of each commented line. When writing block comments, insert a blank line above them, and another one below each paragraph.</p>

					<p>Be careful when using <a name="idx1073749520"></a>
						<a naMe="idx1073749521"></a>inline comments because it can cause over-pollution of text in your code梒omments are no substitute for readable code. Inline comments are best used when preceded by at least two whitespace characters from the inline statement.<A namE="idx1073749522"></a>
						<a naMe="idx1073749523"></a>
						<a NAME="idx1073749524"></a>
						<a naME="idx1073749525"></A>
						<A name="idx1073749526"></A>
						<A NAme="idx1073749527"></a>
						<a NAME="idx1073749528"></a>
						<a name="idx1073749529"></a>
						<a name="idx1073749530"></a>
						<a name="idx1073749531"></a>
						<a NamE="idx1073749532"></a>
						<a nAme="idx1073749533"></a>
						<a Name="idx1073749534"></A>
						<A NAme="idx1073749535"></a>
						<a NAME="idx1073749536"></a>
					</p>

					<p>A <a NAME="idx1073749537"></a>
						<a naME="idx1073749538"></A>
						<I>documentation string</i> is a special kind of comment that goes beyond the <i>remarking concept</i> that we get when using the <tt class="monofont">#</tt> literal. All objects that accept the usage of documentation strings incorporate those strings to their structure, allowing you to later query, read, and use their documentation strings (see <a href="22.html">Chapter 2, "Language Review,"
						</a>  for details).</p>

					<p>Documentation strings are, by convention, surrounded by a <A naMe="idx1073749539"></a>
						<a Name="idx1073749540"></a>triple quote structure on each side. Do not use the documentation string to store a description. Instead, try to be functional, showing the command's action. Things that you should try to register in documentation strings include: the environment variables, files, routine objective, and the syntax design of scripts, modules, functions, classes, and public methods exported by classes.</P>

					<p>There are two types of documentation strings: the one-liners and the multi-line ones. The former must entirely fit in a single line, including the closing quotes, and you are not instructed to insert blank lines surrounding it. On the other hand, multi-line documentation strings are formed by a single line of documentation followed by a block that contains a complete description of the object. Note that we are instructed to insert a blank line between these two structures. Also, note that additional lines in a documentation string do not need to be indented following the pattern established by the first line (it does look nicer if they are though). Before typing the closing quotes, it is also advised that you enter a new paragraph in order to let the quotes stand in a line of their own.<a nAME="idx1073749541"></A>
						<a namE="idx1073749542"></A>
					</P>

					<P>Next, you will have some suggestions about what to include in the documentation string of modules, functions, methods, and classes.</p>

					<p>
						<a nAME="idx1073749543"></A>Modules should document the objects they export, such as the classes, exceptions, and functions, with a one-line summary for each one of them.</p>

					<p>
						<a nAME="idx1073749544"></A>
						<a name="idx1073749545"></a>Functions and methods should document their behavior, arguments (including optional arguments and keywords), return value(s), side effects, exceptions raised, and so forth. When documenting arguments, put each one of them in a single line and separate each name from its description using two dashes. Single blank lines separate lists of methods and functions from each other.</p>

					<p>
						<a name="idx1073749546"></a>Classes should document their public methods and instance variable properties. If the class subclasses another class, you have to mention the <a name="idx1073749547"></a>superclasses as well, along with the differences between both implementations. As a suggestion, use the verbs override and extend to respectively indicate that a specific method entirely replaces, or acts in addition to the superclass's own method definition. It is also recommended that when creating the documentation string for a class, you should surround it using single blank lines.<A naMe="idx1073749548"></a>
						<a Name="idx1073749549"></a>
						<A namE="idx1073749550"></A>
						<A Name="idx1073749551"></a>
						<A NAMe="idx1073749552"></a>
						<a nAME="idx1073749553"></A>
						<a namE="idx1073749554"></A>
						<A Name="idx1073749555"></a>
						<a name="idx1073749556"></a>
						<a name="idx1073749557"></a>
						<a namE="idx1073749558"></a>
						<a Name="idx1073749559"></A>
						<a namE="idx1073749560"></a>
						<a nAME="idx1073749561"></A>
						<a namE="idx1073749562"></A>
						<A Name="idx1073749563"></a>
						<A NAMe="idx1073749564"></a>
					</p>

				
				
					<h4>


Naming Styles and Conventions</H4>
					<P>When it comes time to name your objects and variables, you have a list of options to choose from. You just can't mix all styles throughout your code because it might cause a big mess. You need to be consistent, and I suggest that you stick to a pattern and use it in every part of your code. As I said before, many styles are available. You might already be a big fan of one of them without even knowing it. It is quite common to have different naming conventions for classes, functions, and variables (for instance, <I>CapWords</I> for classes, <i>lower_case_with_underscores</i> for functions). In order to give you an idea of what kind of different styles we have, the following case conventions are introduced to you:</p>

					<blockquote>
<p>
							<p>x (single lowercase letter)</p>

						</p>
<p>
							<p>X (single uppercase letter)</p>

						</P>
<p>
							<p>lowercase</P>

						</p>
<p>
							<p>lower_case_with_underscores</P>

						</p>
<p>
							<p>UPPERCASE</p>

						</P>
<p>
							<p>UPPER_CASE_WITH_UNDERSCORES</p>

						</P>
<P>
							<P>CapitalizedWords (or CapWords)</P>

						</p>
<p>
							<p>mixedCase</p>

						</P>
</BLOckquOTE>
					<P>Capitalized_Words_With_Underscores<a namE="idx1073749565"></A>
						<A Name="idx1073749566"></a>
						<a name="idx1073749567"></a>
						<a name="idx1073749568"></a>
						<a namE="idx1073749569"></a>
						<a Name="idx1073749570"></A>
						<a namE="idx1073749571"></a>
						<a nAME="idx1073749572"></A>
						<a namE="idx1073749573"></A>
						<A Name="idx1073749574"></a>
						<A NAMe="idx1073749575"></a>
						<a nAME="idx1073749576"></A>
					</p>

					<p>The following leading/trailing underscore structures can be combined with any one of the previously listed naming styles. You can substitute the variable <tt class="monofont">VAR</tt> for any other <a name="idx1073749577"></a>object name that you want (considering Python's rules for object naming seen in <a hrEf="22.html">Chapter 2</a>).</P>

					<bloCkquoTe>
<p>
							<p>
								<TT CLass="monofont">_VAR</tT> 棤
    Objects that have a single leading underscore indicate that the object can be used only on the local module namespace. The <TT Class="monofont">from module import *</TT> statement doesn't import objects that start with a single leading underscore. The main concern about writing global variables is that if you want to have the variable only visible by the module that defines it, you need to have an underscore preceding it.</P>

						</P>
<p>
							<p>
								<tt CLASs="monofont">VAR_</tt> 棤
    You need to append a trailing underscore to the end of the name in order to avoid naming conflicts whenever you want to use a Python keyword (such as <tt class="monofont">print_</tt>) as your own variable. This is one just possible way of getting rid of a conflict with a Python keyword.</p>

						</p>
<p>
							<p>
								<tt clAss="monofont">__VAR</Tt> 棤
    The double leading underscore identifies class-private names.</p>

						</p>
<P>
							<p>
								<tt cLass="monofont">__VAR__</TT>棤
    When you have an object that has both leading and trailing underscores, you can consider yourself in front of an object that, in most cases, is defined by the Python interpreter. This definition applies to both objects and attributes that work under the user namespace, which includes the <TT clasS="monofont">__init__</TT> method. Try to avoid using this type of structure when naming your own objects because it might cause name conflicts in your application as future releases of Python arrive.<A name="idx1073749578"></A>
								</P>

						</P>
</BlockQUOTe>
					<p>Although there is no current naming standard among the files that are part of the Python's Standard Library, I can list some guidelines that can make the task of naming new modules easier for you.<a name="idx1073749579"></a>
						<a name="idx1073749580"></a>
						<a name="idx1073749581"></a>
						<A naMe="idx1073749582"></a>
						<a Name="idx1073749583"></a>
						<A namE="idx1073749584"></A>