Guidelines:CodingStyle - Revision history

Dominic: /* Internationalisation */

2026-10-29T12:58:43Z

Internationalisation

@@ Line 116: / Line 116: @@
              Card secrets will not be rendered.
      """
 </syntaxhighlight>

Dominic: /* Python */

2026-10-29T12:52:16Z

Python

← Older revision		Revision as of 12:52, 29 October 2026
Line 10:		Line 10:

	= Python =		= Python =

			== Line-length and Indentation ==

			Use '''four spaces''' for indentation.

			Try to limit the length of code lines to '''80 characters''', where possible (PEP8). This is not a strict requirement, however:
			* a string literal making the line longer is acceptable as long as it is the last code element in that line
			* a line that is only slightly longer (up to 96 characters) is acceptable if it aids readability/comprehensibility

	== Quotes ==		== Quotes ==

Dominic: /* Python */

2026-10-29T12:26:37Z

Python

← Older revision		Revision as of 12:26, 29 October 2026
Line 126:		Line 126:

	Database exceptions should never be caught as they may block the current transaction and thus lead to another exception at a later point, obscuring the original cause of the problem.		Database exceptions should never be caught as they may block the current transaction and thus lead to another exception at a later point, obscuring the original cause of the problem.

			== Print Function ==

			For compatibility with WSGI as well as newer web2py (>=2.15), using the <code>print()</code> function in web application sources is '''strongly discouraged'''.

			For everything that is to be executed in the restricted environment (i.e. all server code):
			* for messages that are relevant during system setup (e.g. 1st run, module import failures etc.), use <code><nowiki>sys.stderr.write()</nowiki></code>
			* for run-time debug/error messages: use <code><nowiki>current.log.*</nowiki></code>, as it can be controlled centrally, and routed to a log file when web2py isn't console-run
			* for temporary debug output in code under development, use either <code><nowiki>sys.stderr.write()</nowiki></code> or <code><nowiki>print(..., file=sys.stderr)</nowiki></code>


			For CLI scripts:
			* use <code><nowiki>sys.stderr.write()</nowiki></code> for status/error messages, or <code><nowiki>sys.stdout.write()</nowiki></code> for results
			* alternatively, use the <code><nowiki>print()</nowiki></code>-function


			Using <code><nowiki>sys.std*.write()</nowiki></code> (remember that write expects string/buffer, so you must convert any parameters explicitly):

			<syntaxhighlight lang="python">
			import sys

			# For status/error/debug messages:
			sys.stderr.write("Here is a status message\n")

			# For results:
			sys.stdout.write("%s\n" % result)
			</syntaxhighlight>

			Using the logger:
			<syntaxhighlight lang="python">
			from gluon import current

			# Use this for any permanent message output in server code:
			current.log.error("Here is an error message")

			current.log.debug("And this is a debug message")
			</syntaxhighlight>

			Using the print-function:
			<syntaxhighlight lang="python">
			import sys

			# Using the print-function in CLI scripts:
			print("The print-function", "accepts", "multiple arguments")

			# Remember that server code must write to stderr, not stdout:
			print("Direct output to stderr", file=sys.stderr)
			</syntaxhighlight>

	= JavaScript =		= JavaScript =

Dominic: /* JavaScript */

2026-10-29T12:14:12Z

JavaScript

← Older revision		Revision as of 12:14, 29 October 2026
Line 136:		Line 136:
	''tbw''		''tbw''

	==~~= JavaScript =~~==		== Docstrings ==

	In JavaScript, we use Java Docstrings. Type specifications for parameters and return values are mandatory.		In JavaScript, we use Java Docstrings. Type specifications for parameters and return values are mandatory.

Dominic at 12:13, 29 October 2026

2026-10-29T12:13:45Z

Show changes

Dominic: /* Quotes */

2026-10-28T23:08:20Z

Quotes

← Older revision		Revision as of 23:08, 28 October 2026
Line 18:		Line 18:
	Note though that this:		Note though that this:

	<~~code><nowiki~~>		<syntaxhighlight lang="python">
	inline_javascript = '''sometext="%s";''' % sometext		inline_javascript = '''sometext="%s";''' % sometext
	</~~nowiki></code~~>		</syntaxhighlight>

	is a '''potential bug''' - the script breaks when <code>sometext</code> contains a <code>"</code>. A safer way to do that is:		is a '''potential bug and security risk''' - the script breaks when <code>sometext</code> contains a <code>"</code>. A safer way to do that is:

	<~~code><nowiki~~>		<syntaxhighlight lang="python">
	inline_javascript = '''sometext=%s;''' % json.dumps(sometext)		inline_javascript = '''sometext=%s;''' % json.dumps(sometext)
	</~~nowiki></code~~>		</syntaxhighlight>

Dominic at 23:02, 28 October 2026

2026-10-28T23:02:36Z

← Older revision		Revision as of 23:02, 28 October 2026
Line 143:		Line 143:
	Type specifications for parameters and return values are mandatory here.		Type specifications for parameters and return values are mandatory here.

	=== Internationalisation ===		== Internationalisation ==

	* All user-visible strings and labels ''must'' be internationalised: <code>T("My string")</code>		* All user-visible strings and labels ''must'' be internationalised: <code>T("My string")</code>

	=== Exception Handling ===		== Exception Handling ==

	Catching exceptions too broadly can easily hide programming errors, obscure problem causes, and introduce serious risks for data integrity and security. Be as specific as possible as to which (type of) exception is to be caught, and always have a good reason for catching it.		Catching exceptions too broadly can easily hide programming errors, obscure problem causes, and introduce serious risks for data integrity and security. Be as specific as possible as to which (type of) exception is to be caught, and always have a good reason for catching it.

Dominic: /* Exceptions */

2026-10-28T22:56:16Z

Exceptions

← Older revision		Revision as of 22:56, 28 October 2026
Line 147:		Line 147:
	* All user-visible strings and labels ''must'' be internationalised: <code>T("My string")</code>		* All user-visible strings and labels ''must'' be internationalised: <code>T("My string")</code>

	=== ~~Exceptions~~ ===		=== Exception Handling ===

			Catching exceptions too broadly can easily hide programming errors, obscure problem causes, and introduce serious risks for data integrity and security. Be as specific as possible as to which (type of) exception is to be caught, and always have a good reason for catching it.

			Do not catch an exception ("Let it crash") unless:
			* there is an immediate remedy or a meaningful alternative action, or
			* the exception can be transformed into a meaningful error message that the users can act upon, or
			* the exception needs to be logged (in which case it should be re-raised after logging)

			All critical exceptions on the server-side should be logged.

			Database exceptions should never be caught as they may block the current transaction and thus lead to another exception at a later point, obscuring the original cause of the problem.

Dominic at 22:12, 28 October 2026

2026-10-28T22:12:47Z

← Older revision		Revision as of 22:12, 28 October 2026
Line 1:		Line 1:
	* [[Guidelines:Index\|All Guidelines]]		* [[Guidelines:Index\|All Guidelines]]

	== Coding Style Guide ==		= Coding Style Guide =

	These conventions should be followed in all code.		These conventions should be followed in all code.
Line 9:		Line 9:
	Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.		Our style guide aims to make the code base appear as if it was written by one precise punctilious programmer, rather than a a cacophony of competing coders. As with many aspects of coding and writing, there can be differences of opinion about the best style. These issues distract from the goal of writing code that works. Most project contributors have a slightly different personal coding style, but we all use the Sahana Eden style when contributing to the Sahana Eden project.

	=== Quotes ===		== Quotes ==

	* for string literals in '''Python''' use double-quotes <code>" "</code>, unless the string contains double-quotes		* for string literals in '''Python''' use double-quotes <code>" "</code>, unless the string contains double-quotes
Line 35:		Line 35:
	* for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes <code>" "</code> (inner quotes must be escaped anyway)		* for attributes in other '''XML''' (e.g. ''XSLT'') use double-quotes <code>" "</code> (inner quotes must be escaped anyway)

	=== Names ===		== Names ==

	==== General ====		=== General ===

	* Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g.		* Names should be obvious and explicit, but not overly verbose (i.e. as long as they need to be to not make people think). They shouldn't require someone to look in another file or solve a puzzle to figure out what they mean, but shouldn't take too long to write. Avoid inventing new acronyms. e.g.
Line 43:		Line 43:
	good: <code>personnel_search</code>, <code>create_gis_layer</code>		good: <code>personnel_search</code>, <code>create_gis_layer</code>

	==== Python ====		=== Python ===

	* Class names start with an uppercase letter.		* Class names start with an uppercase letter.
Line 64:		Line 64:
	* <code>CRUDMethod</code> subclasses in <code>s3db</code> must start with the all-lowercase module prefix plus underscore, e.g. <code>pr_Contacts</code>		* <code>CRUDMethod</code> subclasses in <code>s3db</code> must start with the all-lowercase module prefix plus underscore, e.g. <code>pr_Contacts</code>

	=== Docstrings ===		== Docstrings ==

	All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used.		All classes and functions must have docstrings that explain what the class or function is intended for and how it is to be used.
Line 72:		Line 72:
	The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.		The function description in the docstring should be a statement in the third person about what the function does — not an imperative instruction telling it what to do.

	==== Python ====		=== Python ===

	We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:		We follow loosely the ''Google Style Guide'' for docstrings in Python, albeit with additional indentation:
Line 122:		Line 122:
	</syntaxhighlight>		</syntaxhighlight>

	==== JavaScript ====		=== JavaScript ===

	In JavaScript, we use Java Docstrings.		In JavaScript, we use Java Docstrings.

Dominic: /* Python */

2026-10-28T22:11:23Z

Python

← Older revision		Revision as of 22:11, 28 October 2026
Line 97:		Line 97:
	</syntaxhighlight>		</syntaxhighlight>

	Except where they are obvious, '''data types''' of parameters and return value should be included in the docstring.		Except where they are obvious, '''data types''' of parameters and return value '''should be included''' in the docstring.

	To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are discouraged for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.		To that end, '''PEP484-style type hints''' can also be acceptable in simple cases - but are '''discouraged''' for more complex parameter lists as they can easily impair comprehensibility, and not every syntax highlighter will aid the visual parsing of function annotations.

	<syntaxhighlight lang="python">		<syntaxhighlight lang="python">