代码命名指南
约 1940 字大约 6 分钟
2025-10-03
为什么需要重视命名?
咱们需要先搞懂为什么要重视编程中的命名这一行为,它对于我们的编码工作有着什么意义。
为什么命名很重要呢? 这是因为 好的命名即是注释,别人一看到你的命名就知道你的变量、方法或者类是做什么的!
简单来说就是 别人根据你的命名就能知道你的代码要表达的意思 (不过,前提这个人也要有基本的英语知识,对于一些编程中常见的单词比较熟悉)。
简单举个例子说明一下命名的重要性。
《Clean Code》这本书明确指出:
好的代码本身就是注释,我们要尽量规范和美化自己的代码来减少不必要的注释。若编程语言足够有表达力,就不需要注释,尽量通过代码来阐述。
举个例子: 去掉下面复杂的注释,只需要创建一个与注释所言同一事物的函数即可
# check to see if the employee is eligible for full benefits
if employee.flags & HOURLY_FLAG and employee.age > 65应替换为
if employee.isEligibleForFullBenefits()常见命名规则及适用场景
驼峰命名法(CamelCase)
驼峰命名法应该我们最常见的一个,这种命名方式使用大小写混合的格式来区别各个单词,并且单词之间不使用空格隔开或者连接字符连接的命名方式。
驼峰命名法常用于 Java, JavaScript, C#, Swift, Go等
大驼峰命名法(UpperCamelCase)
规则:每个单词的首字母都大写。
常用场景:
类名
构造函数
接口名
类型名
举例:
class UserModelclass HttpClientinterface Printablestruct BankAccount
小驼峰命名法(Lower Camel Case)
规则:第一个单词的首字母小写,后续每个单词的首字母大写。
常用场景:
变量名
函数名(方法名)
属性名
举例:
firstNamegetUserInfo()totalAmountfileNameToSave
蛇形命名法(Snake Case)
通过下划线 _ 来分隔单词,形似一条蛇。
规则:所有字母通常为小写(或大写),单词之间用下划线
_连接。变种:
小蛇式 (Lower Snake Case):全部字母小写。这是最常见的形式。
举例:
user_name,calculate_total_price(),max_size大蛇式 (Upper Snake Case / Macro Case):全部字母大写。通常用于常量或预编译宏。
举例:
MAX_CONNECTIONS,PI,DATABASE_URL
常用场景:
变量名、函数名(在某些语言中)
常量(通常用大蛇式)
数据库字段名(如 first_name)
文件名、配置文件键名
常用语言:Python, Ruby, C/C++(用于宏),PHP。在数据库SQL中也非常普遍。
串式命名法 (Kebab Case)
串式命名法通过连字符 - 来分隔单词,形似一串烤肉。
规则:所有字母均为小写,单词之间用连字符
-连接。常用场景:
URL 网址路径:
https://example.com/my-blog-postHTML/CSS 中的类和ID:
<div class="main-content">,#submit-button命令行参数:
npm install --save-dev包名、仓库名(如 npm 包):
react-dom,express-validator重要限制:由于连字符
-在大多数编程语言中会被解释为减号操作符,因此它不能用于变量名或函数名。它的主要舞台在Web前端(HTML/CSS)、命令行工具和URL中。举例:
class="nav-menu"id="user-profile"project-name
Django 代码命名规范
| 组件 | 命名规范 | 示例 |
|---|---|---|
| 项目名 | 蛇形命名法 (小写 + 下划线) | my_blog_project |
| 应用名 | 蛇形命名法,单数名词 | blog, user |
| 模型类 | 驼峰命名法,单数 | User, BlogPost |
| 模型字段 | 蛇形命名法 (小写 + 下划线) | first_name, is_published |
| 视图类 (CBV) | 驼峰命名法,View 结尾 | PostListView, UserCreateView |
| 视图函数 (FBV) | 蛇形命名法 | post_list, user_create |
| URL 名称 | 蛇形命名法,使用应用命名空间 | blog:post_detail |
| 表单类 | 驼峰命名法,Form 结尾 | ContactForm, UserRegistrationForm |
| 模板文件 | 蛇形命名法,.html 后缀 | post_detail.html, user_form.html |
| 模板目录 | app_name/templates/app_name/ | blog/templates/blog/ |
| 自定义设置/常量 | 全大写 + 下划线 | MAX_UPLOAD_SIZE, STATUS_CHOICES |
总体原则
PEP 8: 这是 Python 的基本代码风格指南,所有 Python 代码(包括 Django)都应优先遵守。
文件名: 使用小写字母和下划线,例如
models.py,views.py,my_custom_helper.py。变量/函数名: 使用小写字母和下划线(蛇形命名法),例如
get_user_profile, article_list。类名: 使用大写字母开头的单词(驼峰命名法),例如
BlogPost,UserProfile。常量: 使用全大写字母和下划线,例如
MAX_UPLOAD_SIZE,STATUS_CHOICES。
简洁且具有描述性: 名字要能清晰地表明其用途,但不要过于冗长。
u不如user,user_with_profile不如user(如果模型关系已经清晰)。使用英文: 代码和注释都应使用英文,这是国际通用惯例。
项目和应用(Project & APP)
项目名称 (Project Name):
使用小写字母和下划线,应与项目根目录名一致。
例如:
my_blog_project,ecommerce_platform
应用名称 (App Name):
使用小写字母和下划线,应是一个单数名词,描述其功能范围。
例如:
blog,users,payments,api重要: 在
INSTALLED_APPS中注册时,使用带点路径的格式,例如'blog.apps.BlogConfig',而不仅仅是'blog'(这是现代 Django 的推荐做法)。
模型(Model)
模型类 (Model Class):
单数、大驼峰命名法。表示一个单独的对象。
错误:
class Users(models.Model)正确:
class User(models.Model),class BlogPost(models.Model),class Category(models.Model)
字段 (Fields):
蛇形命名法
使用名词或形容词。对于布尔字段,常用
is_,has_,can_等前缀。例如:
title,published_date,author,is_published,has_verified_email
关系字段 (Relationship Fields):
ForeignKey/OneToOneField: 通常使用相关模型的小写单数形式。Django 会自动在字段名后添加 _id 来创建数据库中的列。例如:
author = models.ForeignKey(User, on_delete=models.CASCADE)-> 数据库列名为author_idManyToManyField: 使用相关模型的小写复数形式。例如:
tags = models.ManyToManyField(Tag)
Meta 内部类:
verbose_name: 单数形式,首字母大写。例如:
verbose_name = "Blog Post"verbose_name_plural: 复数形式,首字母大写。例如:
verbose_name_plural = "Blog Posts"ordering: 通常排序字段列表,例如['-created_date']。
方法 (Methods):
使用蛇形命名法。用于自定义行为的实例方法。
例如:
def get_absolute_url(self):,def publish(self):,def is_overdue(self):
视图 (Views)
基于函数的视图 (FBV):
使用蛇形命名法,描述视图的动作。
例如:
post_list,user_detail,article_create,payment_process
基于类的视图 (CBV):
使用大驼峰命名法,并反映其父类或用途。
例如:
PostListView,UserDetailView,ArticleCreateView,PaymentFormView
URL
URL 模式名称 (URL Pattern Names):
在
urls.py中,使用path()的name参数为每个 URL 模式起一个全局唯一的名称。通常使用app_name:view_name的形式来避免冲突。在 blog/urls.py:
app_name = 'blog' # 应用命名空间 urlpatterns = [ path('', views.PostListView.as_view(), name='post_list'), # name: 'blog:post_list' path('<int:pk>/', views.PostDetailView.as_view(), name='post_detail'), # name: 'blog:post_detail' ]在模板中使用:
{% url 'blog:post_detail' post.pk %}在代码中使用:
reverse('blog:post_detail', kwargs={'pk': post.pk})
模板 (Templates)
目录结构:
在每个应用的 templates 目录下,再创建一个与应用同名的子目录,以避免模板名称冲突。
blog/templates/blog/post_list.htmlusers/templates/users/profile.html
模板文件:
蛇形命名法
名称通常与视图对应。
例如:
post_list.html,user_form.html,registration/login.html,includes/pagination.html(用于局部模板)
模板变量/标签:
蛇形命名法
例如:
{{ post.title }} {% for comment in comment_list %}
表单 (Forms)
表单类 (Form Class):
使用大驼峰命名法,并以
Form结尾。例如:
UserRegistrationForm,ContactForm,BlogPostForm
字段 (Form Fields):
- 与模型字段命名规范一致(蛇形命名法)。
配置和常量 (Settings & Constants)
项目设置 (settings.py):
变量名使用大写字母和下划线。
例如:DEBUG, ALLOWED_HOSTS, DATABASES, STATIC_URL
对于自定义设置,也遵循此规则,例如
MY_CUSTOM_SETTING = ‘some_value’
选择项 (Choices):
- 在模型中定义选择项时,
常量名大写,值可以是整数或字符串。
class Article(models.Model): STATUS_DRAFT = 'draft' STATUS_PUBLISHED = 'published' STATUS_ARCHIVED = 'archived' STATUS_CHOICES = [ (STATUS_DRAFT, 'Draft'), (STATUS_PUBLISHED, 'Published'), (STATUS_ARCHIVED, 'Archived'), ] status = models.CharField(max_length=10, choices=STATUS_CHOICES, default=STATUS_DRAFT)- 在模型中定义选择项时,
