The directions contained herein are guidelines for your patches to be accepted faster. Mainly, I am interested in your ideas and execution, coding style just makes it easier and faster for me and other developers to read your submission.
For this guide, I have borrowed heavily from the Linux kernel style documentation, specifically, SubmittingPatches and CodingStyle. This guide also incorporates ideas from PEP 8. I recommend reading that PEP, since only where this guide directly contradicts PEP 8 should the PEP be ignored. I have made changes reflecting Python, the coding style in place when I became maintainer, and my own development environment.
"Coding style is very personal, and I won't force my views on anybody, but this is what goes for anything that I have to be able to maintain, and I'd prefer it for most other things, too. Please at least consider the points made here." -- CodingStyle by Linus Torvalds
The overall idea to keep in mind while working on WiFi Radar: have fun. And a close second: try to mimic the style of the code in which you are working.
Always give people credit in the CREDITS file.
Use spaces. Indents should be 4 spaces.
Try to keep lines under 80 characters. But this is not a hard limit.
Do not add spaces around the inside of parenthesis. Use one space after a comma in a parameter list or tuple. Do not leave trailing whitespace. Use extra spaces to make some groups of code more readable through vertical alignment.
# (widget, l, r, t, b, xopt, yopt, xpad, ypad) self.cmds_table.attach(self.ifconfig_cmd_label, 1, 2, 1, 2, True, False, 5, 0) self.cmds_table.attach(self.ifconfig_cmd, 2, 3, 1, 2, True, False, 0, 0) self.cmds_table.attach(self.ifconfig_cmd_button, 3, 4, 1, 2, False, False, 0, 0)
Use one empty line between functions/methods. Use two empty lines between classes. If readability would be improved by an empty line used to group associated lines of code, then do it.
Operators should have a space before and after. Unless the operator is the equal sign used with named parameters in a function/method definition or call.
def create_new_profile(self, widget, profile, data=None): self.confFile.set_section(section_name=apname, section_dict=profile)
Use single quotes for non-output literal strings (e.g. dictionary keys). Use double quotes for output strings, particularly where formatting substitution is occurring.
self.logger("We're connecting to %s" % (profile_name, ))
As a recovering Pascal programmer, I like explicit naming of variables and functions. But, there's a limit.
Class names should start with capital letters. Classes should be named as to their purpose. If multiple words are used, do not separate them and capitalize each word. Reasonable abbreviations are encouraged. Examples:
Function/method names are all lowercase. They should be named as to their purpose, which probably means a verb. If multiple words are used, separate the words with underscores, do not capitalize. Reasonable abbreviations are encouraged. Examples:
Variable names are all lowercase. They should be named as to their use, which probably means a noun. If multiple words are used, separate the words with underscores, do not capitalize. Reasonable abbreviations are encouraged. Examples:
Global variables should be avoided. But, when necessary, they should be in all capitals and multiple words should be separated by underscores. Reasonable abbreviations are encouraged. Examples:
Variables masquerading as constants should be treated like global variables, wherever they are found.
Class and function/method variables should be in lowercase and multiple words should be separated by underscores, do not capitalize. Reasonable abbreviations are encouraged. Examples:
Include a usage docstring with every function/method, no matter how
simple and self-explanatory that function is. Example:
def make_section_name(essid, bssid):
""" Returns the combined 'essid' and 'bssid' to make a config file
section name. 'essid' and 'bssid' are strings.
return essid + ':' + bssid
Classes should be a logical group of methods and data.
"Functions should be short and sweet, and do just one thing." -- CodingStyle by Linus Torvalds
Sometimes, particularly with GUI-building code, short is not possible. But keep such a method focused on building and filling the GUI and attaching signals.
Avoid using one-time variables. Unless you need to make multi-step changes to the value of an outer-scope variable or are using a calculated value more than once. If you are prompting the user for a new value and you want to validate it before writing it to the configuration file, use a one-time variable. If you are testing a variable for a value or only feeding the value to another function or process, skip creating a new variable and use the variable your class/function received.
needs_commit = config_file.get_opt_as_bool('DEFAULT', 'commit_required')
if (config_file.get_opt_as_bool('DEFAULT', 'commit_required')):
WiFi Radar uses the standard Python logging module. Use logging.DEBUG for code where understanding the current state of the program and OS will be important to fix a possible bug. Use logging.INFO to update a developer (in active development mode) as to the program's state. Use logging.CRITICAL for those places where you cannot recover from an error and want to pass on a message before crashing.
The logging model will then have three potential states: normal-use mode, where only CRITICAL messages are logged; developer mode, where useful info is provided in the console and the log file; and debug mode, where too much info is saved to a log file for analysis.
I use GIT. Hopefully, you are using GIT or some other source code manager to handle your changes. GIT will help you prepare your commits as patches and will include the commit message as a comment with the patch. Keep the first line of the commit message to a short description (less than 100 characters), possibly followed by a longer explanation.