Nomenclature and programming techniques

Pycraft maintains a scheme for naming variables and controlling code structure in Pycraft; this section details all the information you will need for understanding the structure for the program, in addition to the nomenclature (a series of rules that determines how objects should be named). This section will also help you understand the comments and documentation attached below; we strongly recommend you read this before getting started!

Some of these rules are NOT yet integrated into Pycraft, but will be accommodated into versions of Pycraft greater than or equal to v9.4.0 (or v9.3.1 pre-release found here: https://github.com/PycraftDeveloper/Pycraft-Insider-Preview).

Variables

  • All variables should be named in accordance to its function, or based on a description of the data it stores.

  • There is no limit to the length of the name of a variable as at current there is no limit on the length of a of code.

  • Here are some good examples of variable names. StoreRandomNumber or StoreMapVertexBuffer

Subroutines

  • Subroutines can be of any length, as there is no limit to the length of a of code in Pycraft at present.

  • Subroutines should avoid using global variables as much as possible, as this makes it easier to trace variables and possible bugs. (The exceptions here being the``Class_Startup_variables`` and self variables which are referenced throughout the different modules for Pycraft).

  • Subroutines should be named according to their function, and not be dependent on other code in a specific module to work. (For example, making a random number generator that relies on global variables created elsewhere in a module)

  • Subroutines should only have parameters if they are used within the subroutine.

  • If a function returns a value, then this must be implicitly stated in the documentation here.

Modules

  • All modules should be preceded by the following code, regardless of function:

if not __name__ == "__main__":
    print("Started <Pycraft_<name>>")
    class <name>:
        def __init__(self):
            pass
  • All modules should also be proceeded by the following code, the ‘else’ here is important, this connects to the ‘if’ statement we created above:

else:
    print("You need to run this as part of Pycraft")
    import tkinter as tk
    from tkinter import messagebox
    root = tk.Tk()
    root.withdraw()
    messagebox.showerror("Startup Fail", "You need to run this as part of Pycraft, please run the 'main.py' file")
    quit()
  • If a module does not directly have its own GUI (for example the Achievements GUI is made by the ‘Achievements.py’ file), then it should have ‘Utils’ attached at the end of the name, this specifies that the program contains code that aids the creation of the game. There may already be a suitable ‘Utils’ file already. (If the subroutine your creating involves the use of Tkinter, even if it is to create a GUI, and is NOT part of the installer, then place that code under the ‘Tkinterutils.py’ file).

  • Modules that are only ever used in a thread, must be placed into the ‘ThreadingUtils.py’ file.

  • Modules can be broken down into as many classes as needed, but all subroutines must be placed in classes where possible to help speed up locating code if something does go wrong.

Error Handling

  • No error should pass silently; errors should be grouped into two categories; ‘fatal’ and ‘recoverable’, errors that are deemed to be ‘fatal’ must immediately lead to the termination of the currently running program, and a message displayed through the crash GUI if possible. Non-‘fatal’ errors should be appropriately handled in the relevant module, and if expected to pass silently until a fix is available, then must be logged or printed out to the terminal, so other programmers can fix the error later on to stop it potentially causing problems.

  • All errors should be -where possible- stored in the variable message.

Notices

  • This documentation will be updated after a release of Pycraft, but only the necessary parts will be changed, if something is out of date or there is a mistake, then please contact Tom at thomasjebbo@gmail.com or post the issue in the issues tab so we are made aware!

  • All indentation will be represented by ¬ in the by breakdowns.

  • From here onwards will be the documentation for every in Pycraft, this will be updated regularly. We begin by introducing an overview of what each module and class and subroutine does, then go into a by-analysis, this will be long and if your looking for something specific then we recommend that you use <control+f> to speed up the process!

  • Any other notices will be places here!