代码命名指南

约 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 UserModel
class HttpClient
interface Printable
struct BankAccount

小驼峰命名法(Lower Camel Case)

规则：第一个单词的首字母小写，后续每个单词的首字母大写。
常用场景：
变量名
函数名（方法名）
属性名
举例：
firstName
getUserInfo()
totalAmount
fileNameToSave

蛇形命名法(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-post
HTML/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_id
- ManyToManyField: 使用相关模型的小写复数形式。
  例如：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.html
- users/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)