Eric的个人博客

Appearance

代码命名指南 ​

为什么需要重视命名？ ​

咱们需要先搞懂为什么要重视编程中的命名这一行为，它对于我们的编码工作有着什么意义。

为什么命名很重要呢？ 这是因为 好的命名即是注释，别人一看到你的命名就知道你的变量、方法或者类是做什么的！

简单来说就是 别人根据你的命名就能知道你的代码要表达的意思 （不过，前提这个人也要有基本的英语知识，对于一些编程中常见的单词比较熟悉）。

简单举个例子说明一下命名的重要性。

《Clean Code》这本书明确指出：

好的代码本身就是注释，我们要尽量规范和美化自己的代码来减少不必要的注释。若编程语言足够有表达力，就不需要注释，尽量通过代码来阐述。

举个例子： 去掉下面复杂的注释，只需要创建一个与注释所言同一事物的函数即可

python
# check to see if the employee is eligible for full benefits
if employee.flags & HOURLY_FLAG and employee.age > 65

应替换为

python
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

总体原则 ​

  1. 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。

  2. 简洁且具有描述性: 名字要能清晰地表明其用途，但不要过于冗长。u 不如 user，user_with_profile 不如 user（如果模型关系已经清晰）。

  3. 使用英文: 代码和注释都应使用英文，这是国际通用惯例。

项目和应用(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:

      python
      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 (用于局部模板)

  • 模板变量/标签:

    • 蛇形命名法

    • 例如：

      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):

    • 在模型中定义选择项时，常量名大写，值可以是整数或字符串。
    python
    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)

Last Updated: