程序编写规范（自用）

在日常的学习工作中，经常需要编写程序辅助计算或者画图，为了能让程序更加美观且可读性更强，按照平时的编程习惯，制作了满足自身需求的编写规范。

作为非计算机专业及行业的人，我常用的编程语言为Matlab、Python和Fortran。

1 基本规范

编程过程中，我尽量满足以下规范条件：

• 文件夹结构

  • src 源代码存放目录
  • img 生成的图片存放目录
  • dat 运行过程中依赖的数据文件，主要为一些系数或者参数存放位置，应该为固定不变的文件
  • data 需要处理的数据，作为程序的输入，如仪器观测过程中不断生成的数据。一般为了节约本地空间，我会把需要处理的数据都放到移动硬盘里面，只有在测试过程中，会选择几个数据放进来以便测试
  • doc 编写过程中涉及到的文档存放目录，如编程大纲、计算公式、程序设计等
  • refs 存放编写过程中用到的参考文献，如期刊论文等。与doc的区别在于本文件夹下的文档是前人已经发表的论文
  • old 可正常运行的旧版本备份目录，子文件夹以年月日命名，如old/20221103，子文件夹下应该备份有所有的相关文件。本文件夹存在原因是，可能某个版本的代码编写完成后，后续又需要进行大规模的改动，为避免以后找不到改动前的代码，所以需要本文件夹进行备份
  • dist 存放打包好的可执行文件

• 参数定义及传递

  • 主函数的参数输入，确保每个参数只有一个物理意义

  • 子函数之间尽可能减少传递参数的个数，对参数进行分类传递

  • 尽量减少无效参数的传递，保证传递的每个参数都有其价值

  • 尽量减少使用次数很少的中间量的定义

• 命名规则

  • 过短字符的名称不考虑简写，使用的简写尽量是约定俗成的

  • 定义具有确定含义的函数中间名

  • 定义具有确定含义的变量前缀，以方便对函数内部的变量进行管理。只有同一类的变量比较多时，为了避免和其他变量发生冲突，才需要定义前缀

命名规则可根据个人习惯自行定义，我的定义习惯后续会详细介绍

2 基本框架

在定义函数（或子例程）时，我会习惯在函数名定义之前加上一段描述信息，此处以Python为例，如下所示

''' coding: utf-8
INFO: 测试
date: 2022-11-03 Washy [institutions e-mail]
func:
    test01      - 这是一个测试函数
'''

##----------------------------------------------------------------------##
# INFO: 这是一个测试函数
##----------------------------------------------------------------------##
# Needs: test02.m
##----------------------------------------------------------------------##
# Inputs:
#   a           - 含义 [单位]
# Outputs:
#   b           - 含义 [单位]
##----------------------------------------------------------------------##
#参考文献
# [1] Kudeki, E., & Milla, M. A. (2011). Incoherent Scatter Spectral
#   Theories-Part I: A General Framework and Results for Small Magnetic
#   Aspect Angles. Ieee Transactions on Geoscience and Remote Sensing,
#   49(1), 315-328. doi:10.1109/Tgrs.2010.2057252
##----------------------------------------------------------------------##
# author: Washy [institutions e-mail]
# date: 2022/11/03
##----------------------------------------------------------------------##
#更新内容[Washy 2022/11/03]
##INFO: 描述信息
# 1. 更新一
# 2. 更新二
##----------------------------------------------------------------------##
# 可改进的地方: 详细内容
##----------------------------------------------------------------------##
#输入测试示例[Washy 2022/11/03]
#Inputs:
# a = 10
#Outputs:
# b = 10
##----------------------------------------------------------------------##
def test01(a):
    b = a #[1] eq(1)

    return b 

##----------------------------------------------------------------------##
if __name__ == "__main__":
    a = 10
    b = test01(a,b)
    print('{} = {}'.format(a,b))

基本框架中从上至下的含义如下：

• 文件头部分
  • INFO 对整个程序的功能进行概述行描述
  • date 本程序文件创建日期及作者，中括号里面为单位名称缩写和作者的联系邮箱地址
  • func 本程序文件所包含的函数及其描述
• 函数定义前部分
  • INFO 函数功能描述（必要）
  • Needs 被定义函数依赖的其他自定义函数（非必要）
  • Inputs 函数输入变量（必要）
    • 变量名 - 变量描述，变量如果是物理量，中括号内说明量纲
  • Outputs 函数输出变量（必要）
    • 变量名 - 变量描述，变量如果是物理量，中括号内说明量纲
  • 参考文献 函数引用的参考文献，需要编号（非必要）
  • author 作者名，中括号里面为单位名称缩写和作者的联系邮箱地址（必要）
  • date 函数创建及修改日期（必要）
  • 更新内容 函数发生重大版本更新时添加本部分（非必要）
  • 可改进的地方 函数还存在的改进点，受限于时间、精力等因素，编写软件时可能没有把完全优化（非必要）
  • 输入测试示例 函数调用示例，描述清楚输入及对应的输出结果（非必要）
• 函数定义部分
  • 参考文献引用 如果引用了参考文献中的某个公式，在该行代码后加上参考文献编号及文献内公式编号

• 每一行的内容，都尽量不要超过虚线的长度，虚线的长度来自Matlab编程窗口分割线的宽度。
• 使用其他编程语言时，只需批量替换注释符号即可。

3 命名规则

命名包含文件命名、函数命名和变量命名。命名时，我习惯使用一些关键词来增加可读性，我常用的关键词如下

• 前缀

示例

• rename 重命名函数
• set_date 日期设置函数
• get_data 数据获取函数
• init_paras 初始化参量
• save_img 保存图片
• download_data 下载数据

• 文件、文件夹相关

示例

• rootpath 根目录
• foldpath 文件夹路径
• filename 文件名
• filepath 文件路径，通常由foldpath和filename拼接而成

• 后缀

• 其他: 根据实际问题，以实际处理中遇到的参量名进行定义。