程序编写规范(自用)

Washy
2022-11-03 / 0 评论 / 87 阅读 / 正在检测是否收录...

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

作为非计算机专业及行业的人,我常用的编程语言为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 命名规则

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

  • 前缀
名称 含义 名称 含义
re 重处理 set 设置
get 获取 init 初始化
save 保存 download 下载

示例

  • rename 重命名函数
  • set_date 日期设置函数
  • get_data 数据获取函数
  • init_paras 初始化参量
  • save_img 保存图片
  • download_data 下载数据
  • 文件、文件夹相关
名称 含义 名称 含义
root 根目录 fold 文件夹
file 文件 name 名称
path 路径

示例

  • rootpath 根目录
  • foldpath 文件夹路径
  • filename 文件名
  • filepath 文件路径,通常由foldpathfilename拼接而成
  • 后缀
名称 含义 名称 含义
date 日期 str 字符串
data 数据 main 主函数
  • 其他: 根据实际问题,以实际处理中遇到的参量名进行定义。
0

评论 (0)

昵称
邮箱
网址
取消