CGAL项目代码规范与开发指南详解-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00134/article/details/148505478

CGAL项目代码规范与开发指南详解

cgal The public CGAL repository, see the README below 项目地址: https://gitcode.com/gh_mirrors/cg/cgal

前言

作为计算几何算法库的标杆项目，CGAL(Computational Geometry Algorithms Library)在代码组织和规范方面有着严格的要求。本文将深入解析CGAL项目的代码规范体系，帮助开发者理解并遵循这些规范，从而为项目贡献高质量的代码。

命名规范体系

通用命名规则

CGAL采用了一套独特的命名体系，主要特点包括：

下划线分隔：除概念(concept)外，所有名称都应使用下划线分隔单词，如function_name和Class_name
概念命名特殊规则：概念名称使用大写字母分隔单词，如ConvexHullTraits_2
避免缩写：尽可能使用完整单词，如使用Triangulation而非Tri
常量命名：全部大写，如ORIGIN
类名首字母大写：如Quotient, Orientation
函数名全小写：如is_zero()
布尔函数命名：应以动词开头，如is_empty()而非empty()
宏命名：必须以CGAL_开头

几何对象命名

几何对象的命名有其特殊性：

必须包含维度后缀，如Vector_2和Plane_3
对于动态维度对象，使用_d后缀，如Point_d
静态维度对象则使用模板参数指定维度，如Point<d>

几何数据结构和算法

数据结构命名应反映其维度，如Triangulation_2
算法函数名应包含维度，如convex_hull_3()
谓词成员函数应以is_或has_开头
访问器函数应使用STL风格的命名：
- vertices_begin()返回Vertex_iterator
- edges_circulator()返回Edge_circulator

内核特性命名

内核特性(Kernel traits)的命名最为复杂，分为四大类：

广义谓词：以结果命名，如Has_on_bounded_side_2
构造对象：模式为Construct_type_d，如Construct_point_2
构造过程：
- 构造几何对象：Construct_前缀，如Construct_perpendicular_vector_2
- 计算非几何值：Compute_前缀，如Compute_area_2
操作符替代：如Equal_2替代operator==

每个特性类还应提供返回其实例的成员函数，命名规则为小写的特性名加_object后缀，如less_xy_2_object()

文件命名规范

单个几何对象/数据结构/算法应放在同名文件中，如Triangulation_2.h
不包含单一类的文件不应以大写字母开头
文件名在大小写不敏感系统中也应保持唯一
避免使用特殊字符(:, *, 空格等)
内部头文件应放在Package/internal/目录下

编程规范要求

必须遵守的规则

模板参数typedef：应为所有可能被外部访问的模板参数提供typedef

template <class GeometricTraits_2>
class Something {
public:
    typedef GeometricTraits_2 Geometric_traits_2;
};

const正确性：
- 不修改的引用参数应标记为const
- 不修改对象状态的成员函数应标记为const
- 概念上const但实际需要修改内部缓存的可使用mutable成员
C++风格转型：优先使用static_cast等C++风格转型

头文件保护：必须使用预处理指令防止多重包含

#ifndef CGAL_THIS_IS_AN_EXAMPLE_H
#define CGAL_THIS_IS_AN_EXAMPLE_H
// 内容...
#endif // CGAL_THIS_IS_AN_EXAMPLE_H

代码格式规范

缩进至少两个空格
每行只写一个语句
使用C++风格注释(//)

文件头规范

每个CGAL源文件必须包含标准文件头，包含以下内容：

自动扩展的关键字：
- $URL$：文件规范路径
- $Id$：文件所属版本
SPDX许可证标识符：
- GPL-3+: SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-Commercial
- LGPL-3+: SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-Commercial
作者列表(含可选联系信息)

示例头(GPL版本)

// Copyright (c) 1999,2000,2001,2002 INRIA Sophia-Antipolis (France).
// All rights reserved.
//
// This file is part of CGAL (www.cgal.org).
//
// $URL$
// $Id$
// SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-Commercial
//
// Author(s)     : Monique Teillaud <Monique.Teillaud@sophia.inria.fr>
//                 Sylvain Pion

示例头(LGPL版本)

// Copyright (c) 2000,2001,2002,2003 Utrecht University (The Netherlands),
// ETH Zurich (Switzerland),
// INRIA Sophia-Antipolis (France),
// Max-Planck-Institute Saarbruecken (Germany),
// and Tel-Aviv University (Israel). All rights reserved.
//
// This file is part of CGAL (www.cgal.org)
//
// $URL$
// $Id$
// SPDX-License-Identifier: LGPL-3.0-or-later OR LicenseRef-Commercial
//
// Author(s)     : Herve Bronnimann, Sylvain Pion