文章目录
为了养成良好的代码书写规范,笔者决定以后都按照一种常用的代码注释风格。
Part.Zero General
Chap.I 命名规则
不管之前如何,我希望以后的命名规则是这样的。
Item | Rule | Example | Note |
---|---|---|---|
全局变量 | g_xx | g_count | 很少用全局变量 |
局部变量 | xxxx | satnum | 直接连这写,单词尽量全拼 |
类内私有变量 | _xx_xx | _sat_nums | 下划线命名,统一用小写 |
类内公有变量 | xx_xx | sat_num | 没有最前面的下划线,统一用小写 |
类名 | t_xclass_name | t_gslip_detect | t 代表type ,x 代表类的归属或大致用途,后面是类的名字,不同单词间用下划线_ 分割 |
类私有函数 | _xxXxx | _slipDetect | 前下划线后驼峰 |
类共有函数 | xxXxx | processBatch | 驼峰 |
define常量 | XX | PI | 全大写 |
文件名 | xxx_xxx | cycle_slip.h | 全小写,可以用下划线_ |
注:文件命名尽量不要用大写!
Part.I Python
一些通用笔记
# 代码区域折叠
#region
Your Code
#endregion
Sec.I 文件头
文件头一般包含文件的创作者、功能、历史版本等信息,希望自己以后可以按照如下简洁的风格书写 Python 文件头
# ------------------------------------------------------------------
# FileName: pyxxx.py
# Author: hlgou
# Version: V 1.0
# Created: 2020-12-15
# Description: the main function of the file
# History:
# 2021-09-20 hlgou :Create the file
# 20xx-xx-xx xxxxxxxx :Do some modified
# ------------------------------------------------------------------
Sec.II 函数说明
功能简单的函数,只需在函数前加一行注释,说明函数的功能。
def append2Data(time,pos1):
""" Util: append Time and xyz in Data """
功能复杂的函数,需要说明函数的功能、传入传出参数的含义
def append2Data(time,pos1):
"""
This is the description of the function.
> @param[in] param1: this is the first param
> @param[in] param2: this is the second param
return:
< @param[out] outParam1: this is the first out param
< @param[out] outParam2: this is the second out param
"""
关于注释的位置,本来我习惯是放在函数体外部,这样不用展开函数就可以大致了解函数的功效,但是python的代码自动对齐工具会把注释与函数体分离,所以不得不将注释放在函数体内部。
Sec.III 日志输出
python 自带日志管理模块Logging
,当然也可以用其他高级的日志模块loguru
Python之日志处理(logging模块)https://www.cnblogs.com/yyds/p/6901864.html
Logging 的升级版 loguru,支持彩色输出,支持输出到多个文件,分级别分别输出,过大创建新文件,过久自动删除等等。
https://blog.csdn.net/cui_yonghua/article/details/107498535
下面是我个人常用的配置
logging.basicConfig(filename='my.log',level=logging.INFO,
format='%(asctime)s [%(levelname).1s] <%(filename)-s :%(lineno)-s> : %(message)s',
filemode="w",
)
这是一个使用实例
import logging
# 对 log 的基本配置,设置输出文件、输出日志等级、输出格式等
import logging
logging.basicConfig(filename='my.log',level=logging.INFO,
format='%(asctime)s [%(levelname).1s] <%(filename)-s :%(lineno)-s> : %(message)s',
filemode="w",
)
import logging
logging.debug("This is a debug log.")
logging.info("This is a info log.")
logging.warning("This is a warning log.")
logging.error("This is a error log.")
logging.critical("This is a critical log.")
日志等级(level) | 描述 |
---|---|
DEBUG | 最详细的日志信息,典型应用场景是 问题诊断 |
INFO | 信息详细程度仅次于DEBUG,通常只记录关键节点信息,用于确认一切都是按照我们预期的那样进行工作 |
WARNING | 当某些不期望的事情发生时记录的信息(如,磁盘可用空间较低),但是此时应用程序还是正常运行的 |
ERROR | 由于一个更严重的问题导致某些功能不能正常运行时记录的信息 |
CRITICAL | 当发生严重错误,导致应用程序不能继续运行时记录的信息 |
等级顺序:DEBUG < INFO < WARNING < ERROR < CRITICAL
DEBUG 最详细,CRITICAL 最简略。
Part.II Matlab
matlab 的注释符号
Sec.I 文件头
% ------------------------------------------------------------------
% FileName: matlab.m
% Author: hlgou
% Version: V 1.0
% Created: 2020-12-15
% Description: the main function of the file
% History:
% 2021-09-20 hlgou :Create the file
% 20xx-xx-xx xxxxxxxx :Do some modified
% ------------------------------------------------------------------
Sec.II 函数说明
功能简单的函数
% Determine if a year is a leap year
function whe = leapyear(year)
功能复杂的函数
% This is the description of the function.
%
% > @param[in] param1: this is the first param
% > @param[in] param2: this is the second param
% return:
% < @param[out] outParam1: this is the first out param
% < @param[out] outParam2: this is the second out param
function whe = leapyear(year)
Part.III C++
传送门:C++ 代码书写习惯
Part.IV Fortran
Sec.I 文件头
!* ------------------------------------------------------------------
!* FileName: fxxx.f
!* Author: hlgou
!* Version: V 1.0
!* Created: 2020-12-15
!* Description: the main function of the file
!* History:
!* 2021-09-20 hlgou :Create the file
!* 20xx-xx-xx xxxxxxxx :Do some modified
!* ------------------------------------------------------------------
Sec.II 函数说明
!* This is the description of the function.
!*
!> @param[in] param1: this is the first param
!> @param[in] param2: this is the second param
!return:
!< @param[out] outParam1: this is the first out param
!< @param[out] outParam2: this is the second out param
!* END NOTE
Part.X Document
关于 Markdown 文档或其他文档的目录,一般可以按照下面的方式进行取名
@[TOC]
# Part.I Introduction
# Part.II Main_body
## Chap.I xx
# Reference
# Part.I Outline
# Part.I Introduction
## Chap.I xx
### Sec.I xxx
#### S1.
##### a.
##### b.
# Part.BEG Introduction
# Part.END Conclusions