需要区分在接口方法注释和方法实现的注释.

最新推荐文章于 2023-03-27 15:33:28 发布
最新推荐文章于 2023-03-27 15:33:28 发布
阅读量8.6k 收藏
点赞数
CC 4.0 BY-SA版权
文章标签： 算法 文档
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.youkuaiyun.com/loveyly/article/details/1902610
本文讨论了在接口实现中保持注释一致性的重要性，并提出了如何避免注释冗余的建议。作者强调了应该在实现中添加特有的信息，如算法细节等。

摘要生成于 C知道 ，由 DeepSeek-R1 满血版支持， 前往体验 >

前两天负责review 一些代码, 这些代码的质量都是非常好的, 而且注释也非常的清晰. 不过发现一个问题,  在一个接口的实现类中, 其方法的注释也详细的说明该方法的功能和注意事项. 由于没有看到接口的源文件, 所以不知道该方法对应的接口的注释是怎么杨的. 反正有一个感觉: 这样的注释并不是那么完美的.

通常来说, 我们暴露的都是接口文档, 对于接口中的方法都给于详细的注释描述. 如果在接口方法的实现上也给于同样的注释, 可能会导致一个同步的问题. 我们经常说代码不要沉余, 其实就是为了保证不出现代码不同步的问题.

但是该实现特有的一些信息就还是可以添加到注释中的. 比如具体实现算法等.

loveyly
关注
注释是写在接口上还是实现类上_一起学Rust编程「11」：注释
weixin_39538607的博客
12-03 951
Rust的注释语法注释的写法，主要有2类：// 行注释：本行跟在//后面的内容都是注释的部分 /* 块注释。*/ /* * 多行块注释 * 1. **** * 2. **** * 的 */ /* 另一种风格的多行注释。 */还有一种特殊情况，三个斜线///开头的行注释是Rust的文档注释：/// 定义一个屏幕上的点 pub struct Pixel { /// x轴是从左到右...
IDEA设置无警告的类注释和方法注释
qq_30619437的博客
04-22 2314
文章目录类注释信息Java注释Javadoc标签Javadoc命令IDEA中在创建类时会自动给添加注释关于网上很多注释类注释方法注释--Live Templates为变量关联表达式使用方法注释生成javadoc 类注释信息 Java注释 Java] 支持 3 种注释，分别是单行注释、多行注释和文档注释。文档注释以/**开头，并以*/结束，可以通过 Javadoc 生成 API 帮助文档，Java 帮助文档主要用来说明类、成员变量和方法的功能。 文档注释只放在类、接口、成员变量、方法之前，因为 Javadoc
学了这个，再也不想写各种setter了
dabaoshiwode的博客
10-17 189
今天又来给大家吹一下逼。在公司里边也看了不少的系统了，看到结构清晰、代码清晰的系统时会赞叹能写出这种代码的人是真的牛逼。看到乱七八糟的代码又不写注释的时候也会吐槽：“这写的是啥啊”多看别...
python面向对象（类的多态，鸭子类型）
weixin_30588675的博客
03-11 159
一. 接口类 接口类不能被实例化 在python里没有接口类这种数据类型,没有接口类专门的语法但是 可以通过继承abc模块实现接口的功能 from abc import ABCMeta,abstractmethod class Payment(metaclass=ABCMeta): # 接口类 @abstractmethod def pay(self,money)...
注释是写在接口上还是实现类上_编写接口自动化用例时会遇到哪些问题？
weixin_39629617的博客
11-21 503
本篇文章分享几个接口自动化用例编写过程遇到的问题总结，希望能对初次探索接口自动化测试的小伙伴们解决问题上提供一小部分思路。1、sql语句内容出现错误空格，由于有些字段判断是变量，需要将sql拼接起来，但是在拼接字符串时没有加空格导致报错错误状态，打印出来就好排查啦，一看and和时间连起来了，果然是这里出错　　修改后，能够读到数据库中内容了2.sql语句格式错误检索类型，有些需要加引号，因...
注解放在 interface 和 放在实现中 的区别
u011086811的博客
03-27 1716
如果注解放在实现类中，每个实现类都可以定义自己的注解规则，而不需要遵循接口的注解规则。这使得每个实现类都可以根据自己的需要定义自己的注解，而不需要考虑接口的限制。这种方法的缺点是可能会导致实现类之间的注解使用不一致，从而导致不一致的行为。这意味着实现类必须实现接口中定义的所有方法，并且必须按照接口中定义的注解进行使用。综上所述，将注解放在接口中可以强制所有实现类遵循同样的规则，而将注解放在实现类中可以为每个实现类提供更大的灵活性，但也可能导致不一致的行为。选择哪种方式取决于具体的需求和实现场景。
eclipse让实现类也添加上接口的注释_Java服务器接口快速开发之Servlet详细教程，新手小白必看篇...
weixin_39761696的博客
11-28 299
开发工具和环境由于我们的接口开发语言是 java，那么当然还是以 eclipse 为主。这里我使用的是带有 web 插件的 eclipse。我们俗称 javaEE。(当然很多人会使用 myeclipse 这也不错) 想要搭建服务器，tomcat 当然必不可少。这里使用的是7.0，而且是以插件的形式存在于eclipse 中。 做服务器开发的同学当然知道数据库也是必不可少的，咱不能做一个没有真实数据的...
lcd 1602程序+注释.zip_lcd1602程序加注释
09-24
这个"lcd 1602程序+注释.zip"压缩包包含了一个51单片机控制LCD1602的C语言源代码文件——"lcd 1602.c"，并且附带了详细的注释，方便初学者理解和学习。 LCD1602显示器主要特点： 1. **显示规格**：该屏幕通常为16...
基于opencv传统图像处理算法实现物体尺寸测量系统C++源码+项目说明+详细注释.zip
12-02
OpenCV（开源计算机视觉库）是一个跨平台的计算机视觉和机器学习软件库，它提供了大量的图像处理和分析的函数接口。开发者可以通过使用OpenCV库来实现各种复杂的图像处理任务。在本资源中，OpenCV被用来完成物体尺寸...
从HelloWorld和文档注释开始入门Java编程
09-03
文档注释通常包含类、接口、方法等的描述，可以插入链接、作者、版本信息等。例如，`@author`、`@version`等标签。Java API文档是官方提供的，包含了所有Java类库的详细信息，对于开发者来说是不可或缺的参考资料。 ...
代码编写的规范，java类及api注释方法
07-29
学习java编写编写的知道要有一个很好的代码编写规范的习惯，最好每个class，每个api最好都要最好的注释格式，此工具可以帮你解决这些访问，此工具导入到eclipse中，在class或者api上打上‘/**’然后回车，会自动生成注释格式
Java关键字、标识符、注释、转义字符.docx
11-20
Java 关键字、标识符、注释、转义...在 Eclipse 中，\n 和 \r 没有区别，需要在 DOS 环境下运行。 理解 Java 关键字、标识符、注释和转义字符是编写 Java 代码的基础，这些概念对于 Java 语言的学习和应用非常重要。
实现类去实现接口的时候，将接口的注释一起重写出来设置
weixin_45156786的博客
04-20 220
https://blog.csdn.net/qq_40262372/article/details/117018104
java代码注释规范
FairyKunKun的博客
03-29 1984
遵循原则 1. 形式统一 在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其它项目中发现它们的注释规范与这份文档不同，按照这份规范写代码，不要试图在既成的规范系统中引入新的规范。 2. 内容准确简洁 内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。 注释条件 1. 基本注释（必须加） 类（接口）的注释 构造函数的注释 方法的注释 全局变量的注释 字段/属性的注释 简单的代码做简单注释，注释内容不大于10个字即可，另外，持久化对象或VO对象.
C/C++代码规范注释有哪些讲究？
strongerHuang
11-09 1062
关注、星标公众号，不错过精彩内容编排 |strongerHuang微信公众号：strongerHuang如果领导给你一个项目的源码让你阅读，并理解重构代码，但里面一句注释都没有，我想这...
Java注释规范整理
gyhgc的专栏
08-06 1266
在软件开发的过程中总是强调注释的规范，但是没有一个具体的标准进行说明，通常都是在代码编写规范中简单的描述几句，不能作为一个代码注释检查的标准和依据，做什么都要有一个依据吗:),现在我特整理了一个《Java的注释规范》，内容来自网络、书籍和自己的实际积累。 JAVA注释规范 版本/状态 作者 版本日期 1.0 ghc 2008-07-02 一、背景 1、...
详解Java基础中注释添加的位置以及原则
2301_76740033的博客
03-08 641
在之前的文章中学习了不少关于java注释的方式以及快捷操作，有些人还不清楚应该注释的位置，以及注释时需要注意的原则。注释位置为类，接口、方法、常量、关键算法，原则有注释形式统一和注释内容准确简洁。我是李老师说Java，专注Java各类问题的解决、Java最新技术的分享、Java零基础到精通的教学，关注我，带你开启程序开发之路。在这里，我们需要使用javadoc注释，需要标明，创建者，创建时间，版本，以及该类的作用。内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。
进一步解释：区分接口文档与实现注释的定位差异
最新发布
03-25
<think>好的，用户现在让我进一步解释“区分接口文档与实现注释的定位差异”。首先，我需要回顾之前的对话，确保理解上下文。之前用户询问了关于代码注释和Doxygen的使用规范，特别是接口文档与实现注释的区别。现在用户需要更深入的解释，所以我得详细展开这个部分。 用户可能是开发人员，或者正在学习编程规范，特别是如何有效编写注释。他们可能在实际工作中遇到了如何正确注释代码的问题，或者需要理解为什么头文件和源文件的注释方式不同。用户可能希望了解这两者的具体区别，以及实际应用中的例子，以便更好地应用在自己的项目中。 接下来，我需要分解这个问题。接口文档通常位于头文件，供其他开发者使用该函数或模块时参考，而实现注释在源文件中，解释内部逻辑和实现细节。用户可能需要知道两者的目的、内容、格式以及工具处理方式的不同。 我需要考虑用户可能的疑惑点。例如，为什么不能在源文件中使用Doxygen注释？或者，实现注释应该包含哪些内容？可能需要用例子来说明，比如头文件中的函数说明参数和返回值，而源文件中的注释解释算法选择或并发控制。 另外，用户可能想知道这样做的好处，比如维护性和可读性的提升。需要强调接口文档的稳定性和实现注释的变动性，以及工具如Doxygen如何处理不同位置的注释。 可能还需要提到一些反例，比如错误地将实现细节写在接口文档中，或者反之，导致文档混乱。同时，给出正确的示例，帮助用户直观理解差异。 最后，确保回答结构清晰，分点列出，使用表格或代码示例来增强可读性。避免使用技术术语过多，但必要时需准确，保持语言简洁明了。</think>以下是关于接口文档与实现注释定位差异的详细解释，通过对比表格和示例说明其核心区别： --- ### **一、本质定位对比** | **维度** | **接口文档** | **实现注释** | |------------------|----------------------------------------------------------------------------|------------------------------------------------------------------------------| | **核心目标** | 说明 *"怎么用"* (API契约) | 解释 *"怎么实现"* (内部逻辑) | | **目标读者** | 函数调用者（外部开发者） | 代码维护者（内部开发团队） | | **内容重点** | 功能描述、参数约束、返回值含义、错误处理、线程安全等级 | 算法选择依据、优化技巧、代码结构说明、非直观操作的解释 | | **稳定性** | 高（随接口定义变化） | 低（随实现细节调整） | | **工具处理** | Doxygen会提取生成API文档 | 通常不作为公开文档输出 | --- ### **二、典型内容差异** #### **1. 接口文档示例（头文件）** ```c /** * @brief 计算两个向量的点积 * @param[in] vec1 第一个向量指针，长度必须为dim * @param[in] vec2 第二个向量指针，长度必须为dim * @param[in] dim 向量维度，必须大于0 * @return 点积计算结果 * @warning 不检查指针有效性，调用者需确保内存合法 * @note 单线程性能：2.3 cycles/element (AVX2优化) */ float dot_product(const float* vec1, const float* vec2, int dim); ``` **关键特征**： - 定义输入输出的 *契约关系* - 明确使用约束（`dim`限制） - 说明性能特征和硬件依赖 #### **2. 实现注释示例（源文件）** ```c /* * 使用SIMD并行计算点积，实现要点： * 1. 循环展开4次以隐藏指令延迟 * 2. 手动对齐内存访问（需保证vec1/vec2按32字节对齐） * 3. 剩余元素处理采用标量计算 * 注意：此处未加锁因调用方保证单线程上下文 */ float dot_product(const float* vec1, const float* vec2, int dim) { __m256 sum = _mm256_setzero_ps(); // 主循环处理对齐块 for(int i=0; i<dim/8; i++){ __m256 a = _mm256_load_ps(vec1 + i*8); __m256 b = _mm256_load_ps(vec2 + i*8); sum = _mm256_fmadd_ps(a, b, sum); // FMA指令优化 } // ... 后续处理 } ``` **关键特征**： - 解释 *实现策略*（SIMD优化） - 说明 *关键代码段的意图*（循环展开目的） - 记录 *特殊上下文*（单线程假设） --- ### **三、分离的必要性** 1. **信息污染防护** - 接口文档混入实现细节 ➜ 使用者被无关信息干扰 - 实现注释包含API说明 ➜ 维护者可能忽略同步更新 2. **变更影响隔离** ```mermaid graph LR 接口变更 --> 需更新头文件文档 实现优化 --> 仅需修改源文件注释 ``` 3. **工具协作优化** - Doxygen自动提取头文件注释生成API手册 - 静态分析工具可检查实现注释与代码一致性 --- ### **四、错误实践案例** #### **混淆案例（需避免）** ```c // 头文件中错误添加实现细节 /** * @brief 快速排序实现 * 采用Lomuto分区方案，递归深度超过log2(n)时切换堆排序 */ void qsort(int* arr, int n); // 源文件中冗余描述接口 /* 这个函数用来排序数组 */ void qsort(int* arr, int n) { // 函数的作用是排序... } ``` #### **修正方案** ```c // 头文件（纯接口文档） /** * @brief 对整型数组进行升序排序 * @param[in,out] arr 待排序数组指针 * @param[in] n 数组元素个数 * @note 时间复杂度：平均O(n log n) */ void qsort(int* arr, int n); // 源文件（实现注释） /* * 混合排序策略： * 1. 基础使用Lomuto分区快速排序 * 2. 递归深度超过log2(n)时切换堆排序避免最坏情况 * 3. 小数组(n<16)改用插入排序优化缓存 */ void qsort(int* arr, int n) { // 实现细节... } ``` --- ### **五、最佳实践总结** 1. **接口文档三要素** - 功能契约（输入输出关系） - 使用约束（前置/后置条件） - 质量属性（线程安全、复杂度） 2. **实现注释三原则** - 解释 *为什么* 这么做（设计决策） - 记录 *如何* 达到目标（关键步骤） - 警告 *隐藏的陷阱*（特殊处理逻辑） 通过严格区分二者，可构建自我解释的代码体系，降低维护成本，提升协作效率。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值