Community/assets/code-style.html-Dft_PBAz.js

import{_ as n,c as s,o as a,e}from"./app-CmntYhet.js";const p={},t=e(`<h1 id="代码风格指南" tabindex="-1"><a class="header-anchor" href="#代码风格指南"><span>代码风格指南</span></a></h1><h2 id="rust语言代码风格" tabindex="-1"><a class="header-anchor" href="#rust语言代码风格"><span>Rust语言代码风格</span></a></h2><p>  这篇文档将会介绍DragonOS中的Rust语言代码风格。随着开发的进行，这些风格可能会发生变化，但是我们会尽量保持风格的一致性。</p><h3 id="_1-命名" tabindex="-1"><a class="header-anchor" href="#_1-命名"><span>1. 命名</span></a></h3><p>  这部分基于Rust语言圣经中的<a href="https://course.rs/practice/naming.html" target="_blank" rel="noopener noreferrer">命名规范</a>进行修改，本文未提及的部分，请参考Rust语言圣经中的<a href="https://course.rs/practice/naming.html" target="_blank" rel="noopener noreferrer">命名规范</a>。</p><h3 id="_2-格式" tabindex="-1"><a class="header-anchor" href="#_2-格式"><span>2. 格式</span></a></h3><h4 id="_2-1-缩进" tabindex="-1"><a class="header-anchor" href="#_2-1-缩进"><span>2.1 缩进</span></a></h4><p>  请在提交代码之前，使用<code>cargo fmt</code>命令对代码进行格式化。</p><h4 id="_2-2-函数返回值" tabindex="-1"><a class="header-anchor" href="#_2-2-函数返回值"><span>2.2 函数返回值</span></a></h4><p>  尽管Rust可以返回函数的最后一行的语句的值，但是，这种方式会使代码的可读性变差。因此，我们推荐您在函数的最后一行使用<code>return</code>语句，而不是直接返回值。</p><div class="language-rust line-numbers-mode" data-highlighter="prismjs" data-ext="rs" data-title="rs"><pre class="language-rust"><code><span class="line"><span class="token comment">// 不推荐</span></span>
<span class="line"><span class="token keyword">fn</span> <span class="token function-definition function">foo</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">-&gt;</span> <span class="token keyword">i32</span> <span class="token punctuation">{</span></span>
<span class="line">    <span class="token number">1</span> <span class="token operator">+</span> <span class="token number">2</span></span>
<span class="line"><span class="token punctuation">}</span></span>
<span class="line"></span>
<span class="line"><span class="token comment">// 推荐</span></span>
<span class="line"><span class="token keyword">fn</span> <span class="token function-definition function">foo</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">-&gt;</span> <span class="token keyword">i32</span> <span class="token punctuation">{</span></span>
<span class="line">    <span class="token keyword">return</span> <span class="token number">1</span> <span class="token operator">+</span> <span class="token number">2</span><span class="token punctuation">;</span></span>
<span class="line"><span class="token punctuation">}</span></span>
<span class="line"></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h4 id="_2-3-错误处理" tabindex="-1"><a class="header-anchor" href="#_2-3-错误处理"><span>2.3 错误处理</span></a></h4><p>  DragonOS采用返回Posix错误码作为<strong>模块间错误处理</strong>的方式。为了确保在模块之间，错误处理代码的一致性，我们推荐在发生错误的时候，返回<code>SystemError</code>类型，该类型表示posix错误码。这样做的优点尤其体现在跨模块调用函数时，可以直接返回通用的错误码，从而降低错误处理代码的耦合度。</p><div class="language-rust line-numbers-mode" data-highlighter="prismjs" data-ext="rs" data-title="rs"><pre class="language-rust"><code><span class="line"><span class="token comment">// 函数跨越模块边界时（由其他模块调用当前函数），不推荐</span></span>
<span class="line"><span class="token keyword">fn</span> <span class="token function-definition function">foo</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">-&gt;</span> <span class="token class-name">Result</span><span class="token operator">&lt;</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token class-name">CustomErr</span><span class="token operator">&gt;</span> <span class="token punctuation">{</span></span>
<span class="line">    <span class="token keyword">if</span> <span class="token number">1</span> <span class="token operator">+</span> <span class="token number">2</span> <span class="token operator">==</span> <span class="token number">3</span> <span class="token punctuation">{</span></span>
<span class="line">        <span class="token keyword">return</span> <span class="token class-name">Ok</span><span class="token punctuation">(</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line">    <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token punctuation">{</span></span>
<span class="line">        <span class="token keyword">return</span> <span class="token class-name">Err</span><span class="token punctuation">(</span><span class="token class-name">CustomErr</span><span class="token punctuation">::</span>error<span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line">    <span class="token punctuation">}</span></span>
<span class="line"><span class="token punctuation">}</span></span>
<span class="line"></span>
<span class="line"><span class="token comment">// 函数跨越模块边界时（由其他模块调用当前函数），推荐</span></span>
<span class="line"><span class="token keyword">fn</span> <span class="token function-definition function">foo</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">-&gt;</span> <span class="token class-name">Result</span><span class="token operator">&lt;</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token class-name">SystemError</span><span class="token operator">&gt;</span> <span class="token punctuation">{</span></span>
<span class="line">    <span class="token keyword">if</span> <span class="token number">1</span> <span class="token operator">+</span> <span class="token number">2</span> <span class="token operator">==</span> <span class="token number">3</span> <span class="token punctuation">{</span></span>
<span class="line">        <span class="token keyword">return</span> <span class="token class-name">Ok</span><span class="token punctuation">(</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line">    <span class="token punctuation">}</span> <span class="token keyword">else</span> <span class="token punctuation">{</span></span>
<span class="line">        <span class="token keyword">return</span> <span class="token class-name">Err</span><span class="token punctuation">(</span><span class="token class-name">SystemError</span><span class="token punctuation">::</span><span class="token constant">EINVAL</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line">    <span class="token punctuation">}</span></span>
<span class="line"><span class="token punctuation">}</span></span>
<span class="line"></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>  在<strong>模块内部</strong>，您既可以采用返回自定义错误enum的方式，也可以采用返回<code>SystemError</code>的方式。但是，我们推荐您在模块内部，采用返回自定义错误enum的方式，这样可以使错误处理代码更加清晰。</p><p>  <strong>TODO</strong>: 将原有的使用i32作为错误码的代码，改为使用<code>SystemError</code>。</p><h3 id="_3-注释" tabindex="-1"><a class="header-anchor" href="#_3-注释"><span>3. 注释</span></a></h3><p>  DragonOS的注释风格与Rust官方的保持一致。同时，我们推荐您在代码中加入尽可能多的有效注释，以便于其他人理解您的代码。并且，变量、函数等声明，遵守第一节中提到的命名规范，使其能够“自注释”。</p><h4 id="_3-1-函数注释" tabindex="-1"><a class="header-anchor" href="#_3-1-函数注释"><span>3.1 函数注释</span></a></h4><p>  函数注释应该包含以下内容：</p><ul><li>函数的功能</li><li>函数的参数</li><li>函数的返回值</li><li>函数的错误处理</li><li>函数的副作用或者其他的需要说明的内容</li></ul><p>  函数注释的格式如下：</p><div class="language-rust line-numbers-mode" data-highlighter="prismjs" data-ext="rs" data-title="rs"><pre class="language-rust"><code><span class="line"><span class="token comment">/// # 函数的功能</span></span>
<span class="line"><span class="token comment">/// </span></span>
<span class="line"><span class="token comment">/// 函数的详细描述</span></span>
<span class="line"><span class="token comment">/// </span></span>
<span class="line"><span class="token comment">/// ## 参数</span></span>
<span class="line"><span class="token comment">/// </span></span>
<span class="line"><span class="token comment">/// - 参数1: 参数1的说明</span></span>
<span class="line"><span class="token comment">/// - 参数2: 参数2的说明</span></span>
<span class="line"><span class="token comment">/// - ...</span></span>
<span class="line"><span class="token comment">/// </span></span>
<span class="line"><span class="token comment">/// ## 返回值</span></span>
<span class="line"><span class="token comment">/// - Ok(返回值类型): 返回值的说明</span></span>
<span class="line"><span class="token comment">/// - Err(错误值类型): 错误的说明</span></span>
<span class="line"><span class="token comment">/// </span></span>
<span class="line"><span class="token comment">/// ## Safety</span></span>
<span class="line"><span class="token comment">/// </span></span>
<span class="line"><span class="token comment">/// 函数的安全性说明</span></span>
<span class="line"></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div>`,23),l=[t];function c(i,o){return a(),s("div",null,l)}const u=n(p,[["render",c],["__file","code-style.html.vue"]]),d=JSON.parse('{"path":"/contributors/code-style.html","title":"代码风格指南","lang":"zh-CN","frontmatter":{},"headers":[{"level":2,"title":"Rust语言代码风格","slug":"rust语言代码风格","link":"#rust语言代码风格","children":[{"level":3,"title":"1. 命名","slug":"_1-命名","link":"#_1-命名","children":[]},{"level":3,"title":"2. 格式","slug":"_2-格式","link":"#_2-格式","children":[]},{"level":3,"title":"3. 注释","slug":"_3-注释","link":"#_3-注释","children":[]}]}],"git":{"updatedTime":1721563016000,"contributors":[{"name":"LoGin","email":"[email protected]","commits":1}]},"filePathRelative":"contributors/code-style.md"}');export{u as comp,d as data};