最新要闻
- 天猫品牌评估一般几天_天猫品牌评估_最新消息
- 北京电动自行车新规今起实施:电池温度达80度需有报警音
- 世界新消息丨女孩毕业典礼捐10万:含4年奖学金 用于帮助乡村孩子
- 当前观点:高通、联发科找到共同点了:骁龙8G3、天玑9300 AI性能爆发
- 云南普者黑现罕见的粉白相间荷花:花瓣如脂如玉 世界快播报
- ppt讲课技巧互动_ppt讲课技巧 世界视点
- 曼努埃尔·加西亚(关于曼努埃尔·加西亚介绍)
- 新加坡一廉价航班飞机降落后发现少个轮胎:曾出现胎压异常
- 全球领先!刘经南院士:北斗是唯一集通导遥等功能卫星导航系统 新视野
- 民营卫星俯拍四川盆地:中国两项唯一的天府之国 全球焦点
- 世界关注:达标没?调查称53.7%年轻人存款不足10万 感受下中等收入群体收入标准
- 海口一特斯拉高速行驶撞飞小车 官方通报:致一死一伤_当前独家
- 英雄联盟更新不动了怎么办_英雄联盟更新不动
- 柯力传感涨停_焦点短讯
- 一加Ace 2 Pro把骁龙8 Gen2下放!同档位性能无敌-全球观天下
- 国服关了5个月 魔兽世界音乐会重返国内:门票最高680元 世界要闻
广告
手机
iphone11大小尺寸是多少?苹果iPhone11和iPhone13的区别是什么?
警方通报辅警执法直播中被撞飞:犯罪嫌疑人已投案
- iphone11大小尺寸是多少?苹果iPhone11和iPhone13的区别是什么?
- 警方通报辅警执法直播中被撞飞:犯罪嫌疑人已投案
- 男子被关545天申国赔:获赔18万多 驳回精神抚慰金
- 3天内26名本土感染者,辽宁确诊人数已超安徽
- 广西柳州一男子因纠纷杀害三人后自首
- 洱海坠机4名机组人员被批准为烈士 数千干部群众悼念
家电
【环球热闻】Rust语言 - 接口设计的建议之显而易见(Obvious)
Rust语言 - 接口设计的建议之显而易见(Obvious)
- Rust API 指南 GitHub:https://github.com/rust-lang/api-guidelines
- Rust API 指南 中文:https://rust-chinese-translation.github.io/api-guidelines/
- Rust API 指南:https://rust-lang.github.io/api-guidelines/
显而易见(Obvious)
文档与类型系统
- 用户可能不会完全理解接口的所有规则和限制
- 重要:让用户容易理解接口,并难以用错
文档
- 接口透明化的第一步:写出好的文档
- 清楚的记录:
- 可能出现意外的情况,或它依赖于用户执行超出类型签名要求的操作
- 例:panic、返回错误、unsafe 函数...
如果你的代码可能会发生恐慌 panic,要把这一点记录到你的文档里,并且要记录在什么情况下,它会发生恐慌。
如果你的代码要返回错误,要把这一点记录到你的文档里,并且要记录在什么情况下,它会返回错误。
unsafe 函数,要在文档里写明需要满足什么条件才能安全的调用这个函数。
(资料图片仅供参考)
例子一:
// Panic(恐慌)是这两种情况的一个很好的例子:如果代码可能发生 Panic,请在文档中明确说明这一点,以及可能导致 Panic 的情况。// 同样,如果代码可能返回错误,请记录它返回错误的情况。// 对于 unsafe 的函数,请记录调用者必须保证什么条件,才能确保调用时安全的。/// 除法运算,返回两个数的结果。/// /// # Panics////// 如果除数为零,该函数会发生 panic。////// # 示例////// ```/// let result = divide(10, 2);/// assert_eq!(result, 5);/// ```pub fn divide(dividend: i32, divisor: i32) -> i32 { // 实现代码 ...}
- 在 crate 或 module 级,包括端到端的用例
- 不是针对特定类型或方法,了解所有内容如何组合到一起
- 对接口的整体结构有一个相对清晰的理解
- 让开发者快速了解到各方法和类型的功能,以及在哪使用
- 提供定制化使用的起点
- 通过复制粘贴,结合需求进行修改
例子:查看标准库等相关文档
- 组织好文档
- 利用模块来将语义相关的项进行分组
- 利用内部文档链接将这些项相互连接起来
- 考虑使用
#[doc(hidden)]
标记那些不打算公开但出于遗留原因需要的接口部分,避免弄乱文档
例子二:
/// 一个简单的模块,包含一些用于内部使用的函数和结构体。pub mod internal { /// 一个用于内部计算的辅助函数。 #[doc(hidden)] pub fn internal_helper() { // 内部计算的具体实现 ... } /// 一个仅用于内部使用的结构体。 #[doc(hidden)] pug struct InternalStruct { // 结构体的字段和方法 ... }}/// 一个公共接口函数,调用了内部的辅助函数。pub fn public_function() { // 调用内部辅助函数 internal::internal_helper();}/// 一个公共结构体,包含一些公共字段和方法。
- 尽可能的丰富文档
- 可以链接到解释这些内容的外部资源:
- 相关的规范文件(RFC)、博客、白皮书 ...
- 使用
#[doc(cfg(..))]
突出显示仅在特定配置下可用的项- 用户能快速了解为什么在文档中列出的某个方法不可用
- 使用
#[doc(alias = "...")]
可让用户以其他名称搜索到类型和方法 - 在顶层文档中,引导用户了解常用的模块、Trait、类型、方法
- 可以链接到解释这些内容的外部资源:
例子三:
//! 这是一个用于处理图像的库。//!//! 这个库提供了一些常用的图像处理功能,例如://! - 读取和保存不同格式的图像文件 [`Image::load`] [`Image::save`]//! - 调整图像的大小、旋转和裁剪 [`Image::resize`] [`Image::rotate`] [`Image::crop`]//! - 应用不同的滤镜和效果 [`Filter`] [`Effect`]//!//! 如果您想了解更多关于图像处理的原理和算法,您可以参考以下的资源://! - [数字图像处理](https://book.douban.com/subject/5345798/),一个经典的教科书,介绍了图像处理的基本概念和方法。//! - [Learn OpenCV](https://learnopencv.com/),一个网站,提供了很多用OpenCV实现图像处理功能的教程和示例代码。//! - [Awesome Computer Vision](https://github.com/jbhuang0604/awesome-computer-vision),一个GitHub仓库,收集计算机视觉资源。/// 一个表示图像的结构体#[derive(Debug, Clone)]pub struct Image { // ...}impl Image { /// 从指定的路径加载一个图像文件 /// /// 支持的格式有:PNG、JPEG、GIF、BMP 等 /// /// # 参数 /// /// - `path`: 图像文件的路径 /// /// # 返回值 /// /// 如果成功,返回一个 [`Image`] 实例;如果失败,返回一个 [`Error`]。 /// /// # 示例 /// /// ```no_run /// use image::Image; /// /// let img = Image::load("test.png")?; /// ``` #[doc(alias = "读取")] #[doc(alias = "打开")] pub fn load>(path: P) -> Result { // ... } /// 将图像保存到指定的路径 /// /// 支持的格式有:PNG、JPEG、GIF、BMP 等 /// /// # 参数 ///}
例子四:
/// 一个只在启用了 `foo` 特性时才可用的结构体。#[cfg(feature = "foo")]#[doc(cfg(feature = "foo"))]pub struct Foo;impl Foo { /// 一个只在启用了 `foo` 特性时才可用的方法。 #[cfg(feature = "foo")] #[doc(cfg(feature = "foo"))] pub fn bar(&self) { // ... }}fn main() { println!("Hello, world!");}
类型系统
- 类型系统可确保:
- 接口明显
- 自我描述
- 难以被误用
- 语义化类型:
- 添加类型来表示值的意义(不仅仅适用基本类型)
例子五:
fn processDate(dryRun: bool, overwrite: bool, validate: bool) { // 处理数据的逻辑}enum DryRun { Yes, No,}enum Overwrite { Yes, No,}enum Validate { Yes, No,}fn processData(dryRun: DryRun, overwrite: Overwrite, validate: Validate) { // 处理数据的逻辑}processData(DryRun::Yes, Overwrite::No, Validate::Yes);fn main() { println!("Hello, world!");}
- 使用”零大小“类型来表示关于类型实例的特定事实
例子六:
struct Grounded;struct Launched;// and so onenum Color { White, Black,}struct Kilograms(u32);struct Rocket { stage: std::marker::PhantomData,}impl Default for Rocket { fn default() -> Self { Self { stage: Default::default() } }}impl Rocket { pub fn launch(self) -> Rocket { Rocket { stage: Default::default(), } }}impl Rocket { pub fn accelerate(&mut self) {} pub fn decelerate(&mut self) {}}impl Rocket { pub fn color(&self) -> Color { Color::White } pub fn weight(&self) -> Kilograms { Kilograms(0) }}fn main() { println!("Hello, world!");}
#[must_use]
注解- 将其添加到类型、Trait 或函数中,如果用户的代码接收到该类型或 Trait 的元素,或调用了该函数,并且没有明确处理它,编译器将发出警告
例子七:
#[must_use]fn process_data(data: Data) -> Result<(), Error> { // 处理数据的逻辑 Ok(())}// 在这个示例中,我们使用 #[must_use] 注解将 process_data 函数标记为必须使用期返回值。// 如果用户在调用该函数后没有显式处理返回的 Result 类型,编译器将发出警告。// 这有助于提醒用户在处理潜在的错误情况时要小心,并减少可能得错误。fn main() { println!("Hello, world!");}
关键词:
【环球热闻】Rust语言 - 接口设计的建议之显而易见(Obvious)
天猫品牌评估一般几天_天猫品牌评估_最新消息
北京电动自行车新规今起实施:电池温度达80度需有报警音
世界新消息丨女孩毕业典礼捐10万:含4年奖学金 用于帮助乡村孩子
当前观点:高通、联发科找到共同点了:骁龙8G3、天玑9300 AI性能爆发
云南普者黑现罕见的粉白相间荷花:花瓣如脂如玉 世界快播报
ppt讲课技巧互动_ppt讲课技巧 世界视点
【解决方法】锐捷 EVE 模拟器关联 Wireshark 进行抓包 焦点速讯
js-audio-recorder 插件实现web端录音
曼努埃尔·加西亚(关于曼努埃尔·加西亚介绍)
新加坡一廉价航班飞机降落后发现少个轮胎:曾出现胎压异常
全球领先!刘经南院士:北斗是唯一集通导遥等功能卫星导航系统 新视野
民营卫星俯拍四川盆地:中国两项唯一的天府之国 全球焦点
世界关注:达标没?调查称53.7%年轻人存款不足10万 感受下中等收入群体收入标准
海口一特斯拉高速行驶撞飞小车 官方通报:致一死一伤_当前独家
英雄联盟更新不动了怎么办_英雄联盟更新不动
【解决办法】DHCP Relay环境中PC无法获取IP地址,排错与解法 全球新要闻
华为云邓明昆:云原生时代,以开源赋能数字化转型
每日视讯:Quartz.net的最佳实践
动态:【高端访谈】推进金融租赁业务“全绿”转型——专访兴业金租董事长李小东
柯力传感涨停_焦点短讯
一加Ace 2 Pro把骁龙8 Gen2下放!同档位性能无敌-全球观天下
国服关了5个月 魔兽世界音乐会重返国内:门票最高680元 世界要闻
《王者荣耀》S32赛季官宣:又一个双剑战士上线 美人鱼也要来了-每日看点
明年开播!《英雄联盟》电竞剧概念海报发布:张艺谋导演、易烊千玺主演
美国波士顿机场波音737撞上空客321:今年已发生多起类似事件_世界独家
【环球报资讯】画江湖之灵主哪里可以看完整版 画江湖之灵主哪里可以看
世界新资讯:vi命令使用详解
天天热推荐:生态合作 | ShowMeBug入驻集简云平台,多招聘系统管理更便捷
ElasticSearch的使用和介绍
CVE-2023-33246命令执行复现分析 环球观天下
java~搞懂Comparable接口的compareTo方法_天天观焦点
贵州“村超”持续火爆 游客纷纷点赞榕江美食_视讯
天天速读:华为在东莞成立极目机器人公司 注册资本为8.7亿元
不叫C929 中国商飞展出最新宽体远程飞机:载320人飞1.2万公里-当前焦点
官方:国家反诈中心App累计预警3.1亿次 96110电话一定要接!
十几万买豪车将成历史?BBA集体宣布放弃低端车型
最具颠覆性技术 马斯克再次警告:AI有可能给人类带来灾难-每日资讯
全球热门:《塞尔达传说王国之泪》5月份在日本售出150万部
每日报道:使用Flow发送企业应用的通知到微信里
.Net 微服务之旅 天天播报
华为云黄瑾:做强坚实数据底座,GaussDB与产业携手共进
度假区(张渚镇)现场检查国家卫生镇复审工作开展情况
天天快播:华为要求日本通信企业支付专利费 揭秘背后:WiFi 6等专利简直无敌
8月上市!110万的仰望U8要收取豪车税和购置税吗:官方给出答案|世界聚看点
小米系造车成果申报了!增程式越野、智能驾驶拉满:乍看很路虎卫士 环球热讯
《黑袍纠察队》父亲节贺图:祖国人化身"好大儿"-世界热推荐
环球简讯:安卓用户为何加速转投iPhone?原因揭开
每日信息:用电负荷频创新高 央企能源保供备战“迎峰度夏”
中兴通讯(000063):中兴闪耀400G与算力网络时代|全球热消息
环球快看点丨《三体》番外剧《三体:大史》新海报出炉:于和伟主演
关于Cloud-磁盘-分区-物理边界的扩展-扩容
*ST易尚:减持是高管个人权利 公司正准备提交退市复核申请 世界热闻
市区真的能开?小鹏首款MPV曝光 车长5.45米 比腾势D9还大
天天速读:深圳龙华暴雨内涝 街头水深没过车头 比亚迪唐淡定冲浪
成本价曝光!日媒拆小米12T Pro:对中国自研芯片现状感叹 华为笑而不语
世界消息!产品未出周边先行!MOMAX宣布将为Vision Pro开发系列配件
月底全量推送!阿维塔AVP代客泊车有多强:实测逆天|当前速读
中国最富的50个城市——哪里最富?-环球报资讯
焦点热议:Writing for Engineers(作为工程师应该如何写作) —— Stemwede
全球今亮点!强化学习从基础到进阶-案例与实践[1]:强化学习概述、序列决策、动作空间定义、策略价值函数、探索与利用、Gym强化学习实验
【快播报】更好发挥货币政策效能
大获全胜!小米618终极战报来了:卖了194亿、满眼全是第一 天天热资讯
焦点要闻:智能手表鼻祖Pebble复活!推出全新Pebble Cosmos Vogue手表
2023年 为什么住大平层的人迫切想换台电视?
天天通讯!女子买蛋糕遇“空心包装刺客”:神似铜火锅被网友吐槽
江苏省高校辅导员和大学生先进典型颁奖典礼在宁举行
一文读懂ChatGPT的工作原理:大语言模型是个啥?它到底咋工作的? 环球聚焦
世界动态:MySQL中SQL语句的执行顺序(详细)
海外交友源码平台搭建:基础功能的实现(一)
推动戏剧事业高质量发展
售价8.99万元起 钇为3全球上市 重新定义纯电A级车|热讯
谨防诈骗!男子点30块外卖 结果没了2000元|每日热门
实时焦点:Redmi K60系列618杀疯了!全渠道销量破100万台
微动态丨女儿考满分农民工父亲买烧鸡庆祝:趁年轻多挣点钱 让孩子能有选择
网飞《三体》真人剧集中文预告 明年一月上线
天天热推荐:“降息潮”蔓延 “存款特种兵”跨城狂飙
面向故障处理的可观测性体系建设
Spring Boot 优雅实现多租户架构,so easy~!
焦点关注:祸国电视剧免费观看(祸国电视剧)
国产“水果之王”来了!首批国产榴莲6月上市开卖_聚看点
CPU都要烧掉了!女子景区坐竹筏被汽车撞了 网友:头次见|当前要闻
曾经最火SUV!比亚迪宋PLUS冠军版今日上市 买它还是银河L7?
小米MIX Fold 3关键规格曝光:首次用上潜望长焦、更耐摔-天天快看点
黑龙江首列高端旅游列车“林都号”首发:酒吧、茶室全都有
中成股份:6月16日融资买入247.82万元,融资融券余额1.3亿元
山村幼儿园计划-阳光专项基金20000_山村幼儿园计划_全球要闻
避坑指南 篇六:影帝的大肚腩也拯救不了没落的港片。
精彩看点:“楚才还乡”招才引智推介会在北京举办
氧化铝期货上市在即 从定价和套利中或可觅得交易机会_全球滚动
环球快消息!曲阜万仞宫墙南广场区域实行分时段限行 市民游客注意
宝马被大货车横着推出几百米 女司机以为只能等死 网友:远离货车的重要性
青岛新特产“巧克力大爷”火了 网友感慨还玩手机吗:这身体素质秒年轻人_今亮点
长城汽车总裁:‘放血式’价格战不是长久之计 明年目标净利润72亿元 资讯
环球观速讯丨魅族Flyme Auto首次上车 亮点一览:跟手机一样好用
多只债基提前结束募集 超470亿元资金涌向债市 今日关注
讯息:“财务顾问”被判全额连带赔偿 首例ABS欺诈发行案判决结果出炉
曾被长城举报 比亚迪秦/宋PLUS DM-i大批量OTA升级1.2系统
南京大学才女瞒着家里当主播 竟发现榜一大哥是自己爸爸_快讯
售价超50万元理想MEGA却用18英寸小轮胎 李想揭秘:比20英寸好太多