Last Update: March 21, 2015

WiFi Radar - Developer

WiFi Radar v2.x Coding Style Guide

by Sean Robinson

rev. 20140309-01

General

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.

Indentation

Use spaces. Indents should be 4 spaces.

Long Lines and Strings

Try to keep lines under 80 characters. But this is not a hard limit.

Spaces

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.

Example:

# (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.

Example:

def create_new_profile(self, widget, profile, data=None): self.confFile.set_section(section_name=apname, section_dict=profile)

Quotes

Use single quotes for non-output literal strings (e.g. dictionary keys). Use double quotes for output strings, particularly where formatting substitution is occurring.

Example:

self.logger("We're connecting to %s" % (profile_name, ))

Naming

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: ConnectionManager ConfigFile ErrorDialog

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: scanning_thread get_new_profile make_section_name

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: env_tmp self.profile ifconfig_info

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: WIFI_RADAR_VERSION CONF_FILE

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: store self.edit_button error_number error_str

Comments and Documentation

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

Classes should be a logical group of methods and data.

Functions/Methods

"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.

Variables

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.

No: needs_commit = config_file.get_opt_as_bool('DEFAULT', 'commit_required') if (needs_commit): iwcommand.append("commit")

Yes: if (config_file.get_opt_as_bool('DEFAULT', 'commit_required')): iwcommand.append("commit")

Logging Messages

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.

Commit Messages

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.

"Python" and the Python logos are trademarks or registered trademarks of the Python Software Foundation, used with permission. Linux is a registered trademark of Linus Torvalds.