个人对代码注释 & 文档的书写习惯

为了养成良好的代码书写规范，笔者决定以后都按照一种常用的代码注释风格。

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