otree程序设计约定

写在前面：该文档不是otree教程，需要解决otree设计问题请善用开发文档：
oTree — oTree documentation
编写者：胡鑫涛

otree版本管理

旧版otree即将被标注为弃用(deprecated)，请开发者使用最新的otree版本（2.0以上）。
更新otree版本：

pip3 install -U otree

科研组内的otree程序是非开源软件，不遵循GPL或者MIT协议，请不要在github或相关网站上注册你的项目。（如果需要版本管理的功能请在本地使用git工具，并及时做好多端同步。）

otree默认文件

你需要更改的默认的otree APP的文件树如下。需要注意的是，你应该根据代码功能将其编写在合适的文件内。

文件名	功能
`models.py`	数据库存储相关。你需要编写APP详细信息(`author`, `doc`)，常量使用(`Constants`)，收益计算(`Group/Player.set_payoff`)，复杂网络实现(若需要)，游戏初始化赋值(`Subsession.creating_session`，若需要)和数据项存储(`Player`中的字段)之类的信息。
`tests.py`	自动测试和机器人行为，一般不修改。
`views.py`	网页后端数据。你需要编写各个网页的倒计时(`timeout`相关)，是否显示(`is_displayed`)，展示的数据项(`vars_for_template`)和网页顺序(`page_sequence`)等。
`templates/xxx/xxx.html`	网页前端页面。你需要根据`views.py`的变量，编写网页模板。

如果你需要在models.py中使用库，在头部写上import语句即可（一般不建议使用库，因为单个项目迁移有可能导致库缺失）。

如果你自己编写了一个库需要在otree中调用，请使用语句import .xxx来引用你的库。

otree变量名使用

otree程序中的变量和方法命名应该遵循如下规则：

变量名使用全小写字母，下划线分隔。例如：sample_var
(不在Constants内的)常量名使用全大写字母，下划线分割。例如：CONST_VAR
方法名使用全小写字母，下划线分割。例如：def method_to_do(self):
变量名和常量名应该是名词形式，具有含义。例如：player_info_list
方法如果是某种行为，它的名字应该是动词。例如：def generate_rank(self):
方法如果是获取并返回数据，它的名字最好以get_开头。例如：def get_group_payoff(self):
在配置文件中使用的名称，全小写字母，下划线分隔。例如：self.session.config['grid_height']

`Constants`和`session.config`

对于实验中的参数，请注意不要将其固定于代码内！大多数参数应该设计为可调整的，即使这样做会增加代码编写的复杂程度。

参数的判断标准为，设想在真实实验场景下，它的值是否一定不会被修改。如果它一定不会被修改（例如一个方格网络中的个体参与博弈的组数为5），那么请将其写入Constants(Constants.num_play_groups = 5)。如果这个变量可能被修改，则将其写入配置文件中。（具体做法见下文）

(重要) 可以在网页端修改的参数

例如我想让公共品博弈中的收益因子可调整，创建步骤如下：

思考斟酌这个设置的名称。（这一步很重要，因为这个名称不仅在代码中有效，同时也显示在网页中）
在代码中使用self.session.config['multiplier']以访问这个变量。（而不是Constants.multiplier）

写完代码之后，在otree目录的settings.py中增加配置：

 {
     'name': 'xxx',
     'display_name': 'xxx detail name',
     'multiplier': 3,        # 与self.session.config中的对应，"3"同时还有默认值的含义
     'num_demo_participants': 4,
     'app_sequence': ['xxx'],
 },

'num_demo_participants'的默认值可以理解为测试时候的规模，请将它设置得小一点。
接下来这个参数可以在网页中修改了，继续编写文档。

(重要) otree开发文档

`models.py`中的文档

在models.py中你需要留下作者信息和程序介绍，以方便将来维护时的代码询问。在"doc"文档内应该注明程序使用的参数。
例如：

from otree.api import (
    models, widgets, BaseConstants, BaseSubsession, BaseGroup, BasePlayer,
    Currency as c, currency_range
)

author = 'hxt.taoge@gmail.com'    # 最好是填写邮箱，名字也行

doc = """
异质性PGG（中文版本），在某个大小的方格网络内的公共品博弈。
用到的参数（需要在配置文件中添加）：
'width': 2,                # 网格的宽度
'height': 2,            # 网格的高度
'init_money': 50,        # 初始资金
'cost': 5,                # 每轮投资
'multiplier': 3,        # 收益因子
'is_hetero': True,        # 是否为异质性
"""
# ...下面是代码

网页`Sessions`配置页面中的文档

在settings.py中的配置里可以添加一个'doc':"""文档"""的字段，这可地方可以用来编写网页上的文档，这个文档应该依次解释各个配置的含义，要尽可能地详细。

一个完整的配置如下，你可以根据这个'doc'改编你的文档：

    {
        'name': 'hetero_pgg_with_inputbox_cn',
        'display_name': "Heterogeneous PGG with InputBox (Chinese)",
        'width': 2,
        'height': 2,
        'init_money': 50,
        'cost': 5,
        'multiplier': 3,
        'is_hetero': True,
        'num_demo_participants': 4,
        'app_sequence': ['hetero_pgg_with_inputbox_cn'],
        'doc':"""
        <div style="color:red;font-size:30px">注意：请先<b>按照下列说明</b>更改设置！</div>
        1. 点击上方的"Configure session"打开设置面板。<br/>
        2. 修改网络的宽和高，即width和height。<br/>
        3. 修改初始资金，即initial_money。<br/>
        4. 修改每一轮的投资总额，即cost。<br/>
        5. 修改收益因子，即multiplier。<br/>
        5. 若实验为异质性投资，请在is_hetero后面打勾，否则去掉勾。<br/>
        6. 修改玩家个数，即Number of participants，应该使它等于width × height。<br/>
        7. 点击"Create"创建游戏。<br/><br/>
        如果你要创建一个公开的游戏，请使用链接生成器：<a href="http://game.hxtcloud.cn/php/link_producer.php" target="_blank">http://game.hxtcloud.cn/php/link_producer.php</a>。（先打开左边的链接，再返回该页面。）<br />
        具体做法为：<br />
           (1). 复制创建完成后的地址，即地址中包含SessionStartLinks的那个。<br />
           (2). 打开链接生成器，输入你的目标网页名称，以及你复制的SessionStartLinks地址，输入密码并点击生成。<br />
           (3). 记下你生成的地址。
        """
    },

访问页面 http://game2.hxtcloud.cn/create_session/?，点击选择Heterogeneous PGG with InputBox (Chinese)，你将看到这个界面：
Page view

实验人员便可以按照详细的说明创建游戏。

至此，一个otree程序的开发才算结束。