# 项目编程基本原则


## 文档及代码编辑的注意事项

### 进度汇报
**查文档和编程任务是否符合。**

首先自查一遍文档，每个编程任务是否符合文档上编程任务的要求---请在进度表中标示【自查：符合 或 不符合】，是按编程任务，不是按X1,X2...

**查命名问题，函数框架，函数名称，和变量名规范**

(2)按我们前两天讨论的，主函数框架、函数关系调用图、函数名称与变量名称规范化等方面回复【已优化完成，未优化完成】


### 主函数框架示例：

```python
# 需要导入的库

from tkinter import scrolledtext  # 下拉框
from tkinter import END  # 下拉框自动下拉到最后一行
from pymouse import PyMouse  # 模拟鼠标自动点击
import tkinter as tk  # UI界面
import threading  # 多线程任务
import win32gui  # 获取扫雷窗口信息
import random  # 随机数
import time  # 应用sleep函数睡眠

"""按照上宽下窄的方式排列引用"""


"""
所有的系统库或第三方库，一次性引出，避免因为确少库而导致运行不了。
如果是自写的模块，可以在函数前引出
"""

#方式1--在文件中定义全局变量，加载全局变量定义文件（如果全局变量实在太多）
from setting import *  # （setting为自定义程序存放的是全局变量）导入全局变量
# setting中定义了哪些全局变量及其定义 


#方式2--直接定义全局常量和变量（一般多）
全局常量
GLOBAL ... ...      # 常量用大写，大写字母下划线链接
全局变量
Init_Matrix ... ... # 全局变量首字母大写

"""按照上宽下窄的方式排列引用"""



注释标准：
就近对齐规则
print("数据集中图片的个数:", len(data_list))        # 打印图片数据集中图片的个数
print("第一个图片数组的形状:", data_list[0].shape)  # 打印第一个图片数组的形状
print("第一个图片数组的内容:\n", data_list[0])      # 打印第一个图片数组的内容
return data_list  # 返回加载成功的图像数据列表


###########
'此处说明是放函数定义的地方'
###########


# 主控函数, 将函数定义拷贝到main函数上面，将函数调用放在main函数
if __name__ == '__main__':
     pass

    ###########
    '此处说明是函数调用的地方'
    ###########

"""
要求主函数框架单独运行不报错
"""
```

```python
# 文档贴函数提示说明 如下图所示
###########################################################################

# 以func1()[编程章节]==>func2()[编程章节]的方式说明调用当前函数要用的前述函数。
set_random_state()[5.1]==>create_boards()[5.4]==>show_window()[5.4]
```
![img_2.png](img_2.png)

### 根据不同情况不同的贴程序方法

```python
# 情况一
##### 第一次出现init初始化方法需要写全 #####
##### 在类里面增添方法，需要将类名写出，再写方法 #####
X2:
class MineSweeper:  # 建立扫雷类
    def __init__(self):  # 第一次出现init初始化方法需要写全，
    def f2():
      pass

# 情况二
##### 如果函数实在太多，需要标出函数调用关系图，同时将贴合编程要求的程序给出 #####
X3:  # f1(), f2(), f3(), f4(), ..., f10() 本段仅给出f4(), 完整的在[位置]（可以在文档末尾建立附录）。
Class Class_some
    ...
    def f4(): 体现核心功能的函数给出。
        pass
        
# 情况三
##### 如果需要在后续编程章节中扩充原有的功能，可以扩写函数，#####
##### 而且不要出现已经出现过的代码，已经出现过的代码用...代指 #####
X4: 【友好阅读性原则；最小重复代码原则；递增式代码表达原则；界面元素处理与业务逻辑完全分开原则】
class MineSweeper:  # 扩展扫雷类--在X2基础上进一步定义
    # _init_(self), f2(), 一并处理
    def _init_(self): #在原函数基础上增加/调整
      ...
      self.par = "example"
    def f3(): 
      ...
    def f4():
      ...

每个函数不超一页，原则上就是半页。

```

## 项目编程的普遍要求

### GUI界面和数据结构分开

借用前后端分离的架构模式。

GUI界面负责处理用户界面的展示和交互，数据结构部分负责处理业务逻辑和数据处理。

将GUI界面负和数据结构分为两个独立的部分，各自负责不同的功能和任务。GUI界面通过接口函数与更新和加载数据结构。

### 代码命名规则：

在Python中，有一些命名规则和约定被广泛遵循，以提高代码的可读性和一致性。

全局变量：首字母大写单词之间用下划线分隔。

变量和函数名：使用小写字母，单词之间使用下划线（snake_case）进行分隔。例如：my_variable, calculate_result。

常量：使用全大写字母，单词之间使用下划线进行分隔。例如：MAX_VALUE, PI。

类名：使用驼峰命名法（CamelCase），即首字母大写，不使用下划线。例如：MyClass, Calculator。

模块名：使用小写字母，单词之间使用下划线进行分隔。例如：my_module, utils。

- 首先是做好程序的优化，即做好程序函数的封装。 每个函数的函数名尽可能符合文档的编程任务及其要求--要让读者看到函数名就能想到编程任务，这样会更易于理解。

- 函数调用关系图的理解是正确的，就是要有一张全局关系图。

- 正确理解X1、X2、X3、X4和X5。通常，X1仅是围绕数据结构赋值，和界面或者界面元素坐标无关。X2是依据数据结构中的数据做输出，通常是仅输出。X3通常可以定义函数，或者定义类及其中的函数。X4是在X2基础上做界面交互元素，同时将界面交互元素相关的事件/消息绑定X3或X5的函数。X5也是一些函数。这样界面逻辑和业务逻辑是完全分离的。

- 注意：自前向后，编程是越来越复杂，但不要用后面的编程直接替代前面的编程任务中的程序，前面是简单的后面是复杂的。例如“Select Sno from Student”,这是前面的编程，Select :attr1 from :table1"，尽管将attr1赋值成Sno，将table1赋值成Student,也能实现前面的语句，但不可用后面的替换前面的。


### 函数调用关系图：

函数调用图（Function Call Graph）是用于描述程序中函数之间调用关系的图形表示。它展示了函数之间的依赖关系和调用流程，帮助我们理解程序的执行流程和函数之间的交互

在函数调用图中，函数被表示为节点，函数之间的调用关系被表示为边。每个函数调用都会生成一个新的节点和一条连接调用者和被调用者的边。函数调用图可以是有向图或无向图，具体取决于函数调用的方向性。

调用图可以用软件生成。

![img.png](img.png)

### 项目文件应包含(后续规范)
项目应该包含以下基本文件：

1. README.md：项目的说明文档，包含项目的介绍、使用方法、安装指南、贡献指南等重要信息。README.md通常是其他开发者了解和使用项目的入口。

2. LICENSE：项目的开源许可证，明确了项目的使用条件和权利限制。选择适合项目的开源许可证对于保护项目的权益和推动开源合作非常重要。

3. .gitignore：Git版本控制系统的忽略文件配置，用于指定哪些文件或目录应该被忽略，不纳入版本控制。通常包括一些编译生成的文件、临时文件、敏感信息等。

4. requirements.txt：项目的依赖项清单，列出了项目所需的外部库、框架和工具的版本信息。这样其他开发者可以方便地安装相同的依赖项，确保项目的可重复性和一致性。

5. setup.py 或者 setup.cfg：用于打包和发布项目的配置文件。可以定义项目的元数据、依赖关系、安装过程等，以便其他人能够方便地安装和使用项目。

6. docs 目录：包含项目的文档，例如用户手册、API文档、开发者指南等。良好的文档对于其他开发者和用户理解和使用项目非常重要。

7. tests 目录：包含项目的测试代码和测试数据，用于验证项目的正确性和稳定性。包括单元测试、集成测试等，帮助开发者确保项目的质量和可靠性。

8. src 或者 lib 目录：包含项目的源代码文件。根据项目的规模和结构，可以进一步组织成子目录或包，方便代码的组织和维护。

除了上述基本文件，根据项目的特点和需求，还可以包含其他文件，如配置文件、示例代码、演示视频等。重要的是根据项目的具体情况进行文件的组织和描述，确保项目的可理解性、可维护性和可扩展性。

```bash
# 将输出重定向到文件：
pip freeze > requirements.txt
# 老师一键安装项目所有依赖，一般像Pycharm会自动识别这个文件，按提示安装即可
pip install -r requirements.txt
```