编码规范

学习提升 / 编程与深度学习
字数统计: 3.2k   |   阅读时长≈ 12 分钟

1 Matlab编码规范

1.1 命名规则

1.1.1 变量
  • 小驼峰命名法
    • 第一个单词以小写字母开始，后面单词的首字母大写。例如：firstName、lastName。
  • 使用英文
    • 变量名最重要的原则就是，一看就知道这个变量是什么意思。
  • 大范围的变量应带有意义的名称，小范围变量可用短变量名(无意义)
    • 例如：stepSize：大范围意义、dt(δt)：小范围。
  • 循环变量
    • 应该以i、j、k为前缀。例如：iFiles、jPositions。不使用i、j的原因是：这两个在matlab中是虚数。
    • 此外常用循环变量还有：num、iter、count、mark、index、id以及这些循环变量的组合形式。
  • 代表单个实体数据的变量可以加以后缀No
    • 例如：tableNo、employeeNo。
  • 避免否定式的布尔变量命名
    • 例如：若命名isNotFound，在使用判断的时候，~isNotFound，搞半天才知道啥意思。所以不适用否定式布尔变量命名。
  • 拓展变量
    • 释义：就是在已有变量上经过进一步计算得到的新变量，或者与已有变量相关的变量。
    • 策略1：在已有变量的基础上以小驼峰命名的方法在变量的后端添加限定词；
    • 策略2：在已有变量的基础上以小驼峰命名的方法在变量的前端添加限定词；
    • 推荐使用默认使用——策略1。

参考链接1：程序员如何优雅地对变量命名？- idea小时的文章 - 知乎
参考链接2：变量命名规范

1.1.2 常数
  • 全大写字母+下划线
    • 例如：MAX_ITERATIONS、COLOR_RED。
  • 参数可以以某些通用类型名作为前缀
    • 例如：COLOR_RED，COLOR_GREEN，COLOR_BLUE。
1.1.3 结构体
  • 大驼峰命名法
    • 这是区别一般变量，例如：ParameterSet。
  • 结构体的命名应该是隐性的，并且不需要包括字段名
    • 例如：用Segment.length，避免Segment.segmentLength。
1.1.4 函数
  • 函数名应该采用全小写字母+下划线
  • 函数名与它的.m文件名必须相同
  • 函数名应该有具体的意义
    • 避免短的函数名/缩写，这经常使得其名字含糊不清。
    • 例如：采用：compute_total_width()，避免：compwid()
  • 避免无意识地覆盖
    • 有时候我们取的名字，可能在MATLAB中含有这个函数名了，可以用exist检查是否含有了。

1.2 文件与程序结构

1.2.1 .M文件

  • 模块化

    • 编写一个大程序的最好的方法是将它以好的设计分化为小块（通常采用函数的方式）。
    • 这种方式通过减少为了理解代码的作用而必须阅读的代码数量使得程序的可读性、易于理解性和可测试性得到了增强。超过编辑器两屏幕的代码都应该考虑进行分割。并且设计规划很好的函数也使得它在其他的应用中可用性增强了。

  • 确保交互过程清晰

    • 函数通过输入输出参数以及全局变量与其他代码交互通信。使用参数几乎总是比使用全局变量清楚明了。采用结构体可以避免那种一长串儿的输入输出参数的形式。

  • 分割与封装

    • 所有的子函数和所有的函数都应只把一件事情做好。每个函数应该隐藏(hide)一些东西。
    • 任何在多个.m文件中出现的代码块都应该考虑用函数的形式封装起来。

  • 利用现有的函数

    • 开发一个有正确功能的、可读的、合理灵活性的函数是一项有重大意义的任务。或许寻找一个现成的提供了要求的部分、甚至全部功能的函数应该更快也更具有正确性。

  • 子函数

    • 只被另外一个函数调用的函数应该作为一个子函数写在同一个文件中。这使得代码更加利于理解与维护。

  • 测试脚本

    • 为每一个函数写一个测试脚本。这样可以提高初期版本的质量和改进版本的可靠性。

1.3 注释、文档与排版

1.3.1 注释

注释的目的是为代码增加信息。注释的典型应用是解释用法、提供参考信息、证明结果、阐述需要的改进等。经验表明，在写代码的同时就加上注释比后来再补充注释要好。

  • 注释文字应该简洁易读
    • 一个糟糕的或者是无用的注释反而会影响读者的正常理解。N.Schryer提到：“如果代码与注释不一致，那么或许两者都是错误的。”
    • 一个通常更重要的是注释应该讲的是“为什么(Why)”和“怎么做(how)“，而不是“是什么(what)”。
  • 函数的注释写法（英文好的话尽量使用英文） 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
%================================================================
% 功能：       传统LMS滤波算法
% 输入参数：   
%              xn           输入信号
%              mu           步长因子
%              dn           参考信号
%              numIte       迭代次数
%              M            滤波器阶数
% 输出参数：
%              theta        滤波器的系数矩阵
%              en           误差信号
%              yn           滤波器的输出信号
% 备注：		入射角只考虑一个维度的
% 调用方法：	   见XXX文件
% 日期：   	2011/7/12 20:37
%================================================================

function [theta,en,yn] = my_lms(un, dn, mu, Num_iteration, M)
。。。（具体编程开始）
end
1
2
3
4
5
6
7
8
9
10
11
12
13
14
%================================================================
% 功能：	求圆孔的夫琅禾费衍射光强分布
% 参数：	CircleHoleFD为圆孔结构体，包含圆孔衍射相关信息；
% 		   theta为衍射场的次波方向，可以为向量，求取各方向的光强
% 返回值：	I为衍射光强分布
% 主要思路：使用夫琅禾费单缝衍射公式计算
% 备注：	入射角只考虑一个维度的
% 调用方法：见CalcCircleHoleFD_Test文件
% 日期：   2011/7/12 20:37
%================================================================

function I = calcCircleholefd(circleHoleFD, theta)
。。。（具体编程开始）
end
  • 一段代码注释写法
    • 用于理解一小段代码含义的注释，统一写在代码上方，如：
1
2
3
4
5
%（1）初始化 
Number = zeros(1,PNumber);
for i = 1:PNumber 
    Number(i) = MNumber;
end
  • 一句代码注释写法
    • 用于理解一句代码的意思可以写在代码后方，但是注意不能超过180字符。太长可以考虑写在代码上方，如：
1
2
3
4
5
gen = 0;  %迭代计数器 
JmNumber = Max_Cell(Jm);               % 调用Max_Cell子函数求机器的数量 
[PNumber,MNumber] = size(Jm);          % PNumber为工件个数，MNumber为工序个数 
trace = zeros(2, MAXGEN);               % 寻优结果的初始值，一行存放各代的最优解，一行存放各代解的均值 
TotalOP_Number = PNumber*MNumber;      % 工序总个数
1.3.2 文档
  • 文档规范化
    • 作为有用的文档应该包含一个对如下内容的可读性的描述：代码打算干什么（要求），它是如何工作的（设计），它依赖于什其他什么函数以及怎么被其他代码调用（接口），以及它是如何测试的等。对于额外的考虑，文档可以包含解决方案的选择性的讨论以及扩展与维护的建议。

  • 首先考虑书写文档

    • 一些程序员相信的方法是：“代码第一，回答问题是以后的事情。”而通过经验，我们绝大多数人知道先开发设计然后再实现可以导致更加满意的结果。如果将测试与文档留在最后，那么开发项目几乎不能够按期完成的。首先书写文档可以确保其按时完成甚至可能减少开发时间。

  • 修改

    • 一个专业的对代码修改进行管理和写文档的方法是采用源程序控制工具。对于很简单的工程，在函数文件的注释中加入修改历史比什么都不做要好。
1.3.3 排版
  • 空格的使用
    • 在二元运算符两边各空一格[=, -, +=, ==, >, in, is not, and]；
    • 函数的参数列表中，,之后要有空格；
    • 函数的参数列表中，默认值等号两边不要添加空格；
    • 左括号之后，右括号之前不要加多余的空格；
    • 不要为对齐赋值语句而使用的额外空格

本文转自：何亮科学网博客。

链接地址：一些MATLAB的编程规范总结1.0版

其他参考链接：

科研小技巧——MATLAB的编码规范 - 西涯先生的文章 - 知乎

matlab 编程之代码规范 -枯荣有常的文章 - CSDN

MATLAB编程规范 - magic_yu42的文章 - CSDN

1.3.4 绘图、字体设置

王老师关于绘图、字体设置的一些简单设置：PlotCurvesFontSizeFontName.m

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
%% MATLAB曲线图示例设置字号字体

clear all; clc; close all;
%% Lena512.bmp图像
%% X Y分别为编码比特率和峰值信噪比
X1=[0.15 0.20 0.25 0.30 0.40 0.50 0.60 0.75 1.00 1.25];
X2=X1; X3=X1; X4=X1;
Y1=[22.0370 23.4718 24.3595 25.1125 26.5516 27.8992 29.1981 30.8826 33.2239 35.0960];
Y2=[22.5249 23.5379 24.2606 24.9596 26.3507 27.5956 28.7035 30.0974 32.1077 33.7383];
Y3=[22.5594 23.6605 24.3931 25.1403 26.5922 27.8500 28.9936 30.4864 32.5300 34.1851];
Y4=[22.6049 23.7881 24.6194 25.4626 27.0361 28.3933 29.6686 31.3865 33.5905 35.3823];
plot(X1, Y1, '- r .', X2, Y2, '-. b o', X3, Y3, ': m *', X4, Y4, '-- k p', 'LineWidth', 1)
legend('DCT-JPEG', 'APWBT-JPEG', 'APDCBT-JPEG', 'APIDCBT-JPEG')
axis([0, 1.4, 22, 36]);
%% MATLAB的默认字体是Helvetica，fontname的设置，中文字体：宋体、楷体、仿宋、隶书、微软雅黑、幼圆等
%% 英文字体: Times New Roman, Arial, Bodoni, Calibri, Courier New, Frutiger, Futura, Garamond, Geogia, Platino Linotype, Verdana等
xlabel('\fontsize{12}\fontname{宋体}码率\fontname{Times New Roman}(bpp)')
ylabel('\fontsize{12}\fontname{Times New Roman}PSNR (dB)')
set(gca, 'xtick', [0:0.2:1.4], 'ytick', [22:2:36], 'FontSize', 12, 'Fontname', 'Times New Roman');

2 Python编码规范

2.1 编码

无特殊情况，建议Python脚本程序一律使用 UTF-8 编码，并且在文件头部必须加入#-*-coding:utf-8-*-标识，声明文件编码方式，程序文件编码要和声明编码保持一致。

2.2 命名规范

模块： 模块尽量使用小写命名，首字母保持小写，尽量不要用下划线(除非多个单词，且数量不多的情况)

类名： 类名使用驼峰(CamelCase)命名风格，首字母大写，私有类可用一个下划线开头；将相关的类和顶级函数放在同一个模块里。不像Java，没必要限制一个类一个模块。 

1
2
3
4
5
6
7
8
9
class Farm():
    pass

class AnimalFarm(Farm):
    pass

class _PrivateFarm(Farm):
    pass

函数名：

函数名一律小写，如有多个单词，用下划线隔开；

1
2
3
4
5
def run():
    pass

def run_with_env():
    pass

变量名

  • 变量名尽量小写，如有多个单词，用下划线隔开；
1
2
3
if __name__ == '__main__':
    count = 0
    school_name = ''
  • 常量采用全大写，如有多个单词，使用下划线隔开；
1
2
3
MAX_CLIENT = 100
MAX_CONNECTION = 1000
CONNECTION_TIMEOUT = 600

【参考资料1】：【Python】编程代码书写规范！- 科皮子菊的文章 - CSDN

【参考资料2】：PEP8中文版 — Python编码风格指南

2.3 注释

  • 行注释： 以 # 开头，# 右边的所有内容都被当做说明文字，只起到辅助说明作用。 
1
print("hello python")  # 输出 `hello python`

注：为了保证代码的可读性，# 后面建议先添加一个空格，然后再编写相应的说明文字。

  • 多行注释(块注释) ：#号后空一格，段落件用空行分开（同样需要“#”号）。
    • 如果希望编写的 注释信息很多，一行无法显示，就可以使用多行注释。
    • 要在 Python 程序中使用多行注释，可以用 一对连续的 三个引号(单引号和双引号都可以)。
1
2
3
4
5
6
"""
这是一个多行注释；
......
在多行注释之间，可以写很多很多的内容
""" 
print("hello python")

补充： 什么时候需要使用注释？

1、 注释不是越多越好，对于一目了然的代码，不需要添加注释；
2、 对于复杂的操作，应该在操作开始前写上若干行注释；
3、 对于不是一目了然的代码，应在其行尾添加注释（为了提高可读性，注释应该至少离开代码 2 个空格）。

2.4 空格使用

  • 在二元运算符两边各空一格[=, -, +=, ==, >, in, is not, and]

  • 函数的参数列表中，,之后要有空格

  • 函数的参数列表中，默认值等号两边不要添加空格
  • 左括号之后，右括号之前不要加多余的空格
  • 字典对象的左括号之前不要多余的空格
  • 不要为对齐赋值语句而使用的额外空格
  • Copyrights © 2015-2024 wjh
  • 访问人数: | 浏览次数:

请我喝杯咖啡吧~

支付宝
微信