搜索

[24720] 2016-02-17_8个最没有意义的代码注释

文档创建者：s7ckTeam
浏览次数：1
最后更新：2025-01-18
2016-02-17_8个最没有意义的代码注释 8 个 最 没 有 意 义 的 代 码 注 释 译 者 ： 小 峰   L i n u x 中 国   2 0 1 6 - 0 2 - 1 7 编 译 自 ： h t t p s : / / d z o n e . c o m / a r t i c l e s / m y - c o m m e n t a r y - o n - c o d e - c o m m e n t s   作 者 ：   J o h n   V e s t e r 转 载 自 ： 码 农 网   h t t p : / / w w w . c o d e c e o . c o m / a r t i c l e / 8 - u s e l e s s - c o d e - c o m m e n t i n g . h t m l   译 者 ：   小 峰 多 年 来 ， 我 非 常 荣 幸 能 和 一 些 谦 逊 的 公 司 和 客 户 合 作 。 我 也 因 此 有 机 会 接 触 到 各 种 不 同 的 程 序 员 — —   每 个 程 序 员 都 有 自 己 独 特 的 风 格 。 事 实 上 ， 每 个 项 目 本 身 都 有 一 些 独 特 的 元 素 。 这 些 特 质 的 交 叉 让 我 去 思 考 我 曾 经 审 查 、 更 新 或 提 高 过 的 程 序 代 码 。 与 其 说 是 代 码 的 实 际 逻 辑 ， 还 不 如 说 是 开 发 人 员 自 己 添 加 到 代 码 中 的 注 释 ， 对 代 码 产 生 了 颇 为 深 远 的 影 响 。 这 篇 文 章 的 主 题 就 是 罗 列 一 些 我 印 象 深 刻 的 一 些 代 码 注 释 。 c o m m e n t 因 为 因 为 C a r o l 让 我 这 么 做 让 我 这 么 做 我 记 得 审 查 程 序 代 码 时 ， 有 一 条 注 释 是 这 样 写 的 ： 在 阅 读 这 行 代 码 时 ， 我 一 下 子 就 懵 了 ， “ 谁 是 C a r o l ？ ” 以 及 “ C a r o l 让 这 个 开 发 人 员 做 什 么 了 ？ ” 虽 然 写 代 码 的 程 序 员 知 道 这 两 个 答 案 ， 但 换 做 是 一 个 局 外 人 或 者 是 一 个 后 面 加 进 来 的 人 ， 那 么 这 条 注 释 就 毫 无 价 值 。 当 我 和 我 的 经 理 说 起 这 条 注 释 的 时 候 ， 他 哈 哈 大 笑 ， 只 是 说 了 句 C a r o l 明 显 是 一 个 人 名 字 之 后 ， 就 无 下 文 了 。 好 吧 ， 直 到 现 在 ， 我 依 然 不 知 道 这 句 注 释 究 竟 是 什 么 意 思 。 大 段 被 注 释 的 代 码 大 段 被 注 释 的 代 码 在 另 一 种 情 况 下 ， 我 相 信 我 将 问 题 范 围 缩 小 到 了 一 个 特 定 的 类 。 但 是 打 开 这 个 类 ， 我 看 到 大 量 的 代 码 被 块 注 释 掉 了 。 让 人 疯 狂 的 是 ， 注 释 的 代 码 是 在 方 法 的 中 间 。 所 以 ， 我 只 能 在 阅 读 完 顶 部 的 代 码 之 后 ， 滚 动 几 个 屏 幕 ， 才 能 继 续 阅 读 剩 下 的 代 码 。 你 得 牢 记 在 心 里 ， 幸 好 中 间 间 隔 1 .   / /   B e c a u s e   C a r o l   T o l d   M e   t o   D o   T h i s
的 时 间 不 是 太 久 ， 有 到 应 用 程 序 的 源 代 码 库 的 链 接 。 在 我 心 中 ， 我 对 此 非 常 嗤 之 以 鼻 ， “ 提 前 阅 读 没 有 注 释 的 大 块 代 码 ， 却 只 是 看 到 了 程 序 是 用 来 做 什 么 的 ” 。 当 我 问 另 一 名 开 发 人 员 为 什 么 代 码 要 像 这 样 被 注 释 和 检 查 的 时 候 ， 他 给 我 的 回 答 是 “ 万 一 我 们 下 次 还 要 用 到 它 呢 ” 。 我 真 心 无 语 。 只 是 为 了 苦 中 作 乐 只 是 为 了 苦 中 作 乐 在 工 作 于 一 个 基 于 w e b 的 应 用 程 序 时 ， 我 发 现 了 以 下 的 J a v a S c r i p t 注 释 ： 这 里 的 开 发 人 员 意 识 到 D a t e . p a r s e ( ) 方 法 存 在 着 问 题 。 为 了 警 示 他 人 ， 开 发 人 员 决 定 添 加 注 释 作 为 警 告 ， 同 时 又 苦 中 作 乐 了 一 番 。 我 只 能 想 象 当 这 个 开 发 人 员 意 识 到 此 路 不 通 时 心 中 该 是 有 多 么 的 沮 丧 。 道 歉 道 歉 有 些 时 候 ， 程 序 员 意 识 到 他 们 的 做 法 并 不 好 。 很 多 时 候 ， 这 是 基 于 开 发 小 组 之 外 所 能 做 的 唯 一 选 择 。 于 是 ， 出 现 了 这 样 的 注 释 ： 阅 读 代 码 和 理 解 实 施 方 法 背 后 的 情 况 有 助 于 完 整 地 理 解 简 单 的 道 歉 式 注 释 。 这 有 点 像 惊 悚 片 里 的 英 雄 在 采 取 有 计 划 的 行 动 之 前 ， 先 道 歉 的 那 一 幕 。 只 围 绕 它 编 码 只 围 绕 它 编 码 一 开 始 作 为 一 个 白 板 声 明 ， 最 终 被 转 移 到 以 下 注 释 ： 基 本 上 ， 这 是 一 个 进 程 的 入 口 点 ， 代 码 围 绕 明 显 由 E r i c 和 S t e v e 引 入 的 问 题 。 但 是 我 没 有 任 何 相 关 的 背 景 ， 也 不 认 识 E r i c 和 S t e v e ， 我 只 知 道 任 何 影 响 了 他 们 的 代 码 都 得 禁 止 。 为 了 注 释 而 注 释 为 了 注 释 而 注 释 我 们 都 听 过 这 样 一 句 话 ： “ 好 的 代 码 是 自 文 档 化 的 ” 。 我 完 全 同 意 这 种 说 法 ， 当 然 有 些 注 释 还 是 有 必 要 的 。 但 是 ， 下 面 这 种 注 释 ， 明 显 不 能 划 到 “ 必 要 ” 的 范 畴 中 ： 1 .   / /   m a k e   s u r e   i t ' s   c o r r e c t l y   f o r m a t t e d ,   b e c a u s e   i n   j a v a s c r i p t   t h i n g s 2 .   / /   l i k e   ' 7 '   o r   ' 4 . 3 '   o r   ' d e r p d y   d o   7 7 '   a r e   v a l i d   d a t e s 3 .   / /   s e r i o u s l y ,   t r y   i t   o u t   f o r   y o u r s e l f :   D a t e . p a r s e ( ' d e r p d y   d o   7 7 ' ) 1 .   / /   S o r r y   f o r   w h a t   y o u   a r e   a b o u t   t o   s e e 1 .   / /   D o i n g   t h i s   t o   " n o t   d o   a n y t h i n g   t o   e f f e c t   E r i c   a n d   S t e v e ' s   c o d e " 1 .   r e t u r n   t r u e ;   / /   r e t u r n s   t r u e
这 种 注 释 确 明 显 是 没 有 必 要 的 ， 因 为 我 们 很 容 易 理 解 返 回 什 么 。 我 能 想 出 的 关 于 为 什 么 要 这 么 注 释 的 唯 一 原 因 就 是 ， 开 发 人 员 在 添 加 到 实 际 代 码 前 ， 使 用 注 释 先 制 定 出 了 方 法 ， 后 来 却 忘 记 删 掉 这 些 注 释 了 。 但 是 如 果 有 代 码 审 查 过 程 的 话 ， 就 不 会 出 现 这 样 的 注 释 。 注 释 不 正 确 注 释 不 正 确 还 记 得 前 面 提 过 的 “ 好 的 代 码 是 自 文 档 化 的 ” 这 句 话 吗 ？ 那 么 ， 也 许 在 所 有 注 释 中 ， 最 糟 糕 的 就 是 提 供 了 错 误 信 息 的 注 释 。 请 看 下 面 这 个 简 单 的 例 子 ： 现 实 中 我 所 看 到 的 例 子 远 远 没 有 这 么 简 单 。 然 而 更 糟 糕 的 是 ， 当 你 需 要 依 赖 注 释 写 一 个 复 杂 的 方 法 时 ， 才 意 识 到 这 样 的 注 释 是 无 效 的 。 在 这 种 情 况 下 没 有 注 释 都 比 错 误 的 注 释 好 。 小 说 般 的 注 释 小 说 般 的 注 释 最 后 一 种 我 见 过 的 注 释 是 ， 开 发 人 员 写 的 类 似 于 小 说 般 的 注 释 ： 1 .   r e t u r n   t r u e ;   / /   r e t u r n s   t r u e 1 .   / /   A l w a y s   r e t u r n s   f a l s e 2 .   p u b l i c   b o o l e a n   i s A c t i v e ( )   { 3 .           r e t u r n   t r u e ; 4 .   } 1 .   / * * 2 .   *   T h i s   i s   t h e   w i d g e t   m e t h o d   w h i c h   w i l l   p r o c e s s   t h e   l i s t   o f 3 .   *   w i d g e t s   f r o m   t h e   w i d g e t   c o n t r o l l e r   a n d   s e r v i c e   i n   o r d e r   t o 4 .   *   h a n d l e   p r e - p r o c e s s i n g   ( w h e r e   t h e   w i d g e t   i n f o r m a t i o n   i s 5 .   *   c o m p a r e d   a g a i n s t   t h e   a v e r a g e   w i d g e t   h i s t o r y ) ,   a c t u a l 6 .   *   p r o c e s s i n g   ( w h e r e   t h e   q u a r t e r l y ,   m o n t h l y   a n d   w e e k   a t t r i b u t e s 7 .   *   a r e   u p d a t e d )   a n d   a l l   o f   t h e   p o s t - p r o c e s s i n g   ( w h i c h   i n c l u d e   t h e 8 .   *   a n a l y t i c a l   m e t r i c s   a n d   a u d i t   t a b l e   u p d a t e s )   a s p e c t s .   I t   i s 9 .   *   i m p o r t a n t   t o   r e m e m b e r   t h e   w i d g e t   r u l e s   a r o u n d   l e a p   y e a r   w h e r e 1 0 .   *   t h e   c o s t   t o   t r a n s f e r   r a t e   i s   7 5 %   a d j u s t e d   t o   t h e   a n n u a l   r a t e   i n 1 1 .   *   o r d e r   t o   a c c o u n t   f o r   t h e   e x t r a   d a y .   W h e n   t h i s   h a p p e n s ,   t h e 1 2 .   *   p r o c e s s   w i l l   t h r o w   t h e   L e a p Y e a r E x c e p t i o n   w h i c h   w i l l   n e e d   t o   b e 1 3 .   *   v a l i d a t e d   b y   t h e   a p p l i c a t i o n   s u p p o r t   s t a f f .   F a i l u r e   t o   d o   s o   w i l l 1 4 .   *   e n d   u p   c a u s i n g   i s s u e s   w i t h   t h e   M E - 4 1 1 0   r e p o r t . 1 5 .   * /
我 的 经 验 法 则 是 ， 任 何 需 要 那 么 多 信 息 的 代 码 或 许 应 该 分 解 成 更 小 的 方 法 。 而 且 注 释 中 这 样 的 信 息 应 该 挪 到 实 际 的 代 码 之 外 。 而 在 上 面 的 例 子 中 ， 像 流 水 账 一 样 记 录 的 业 务 规 则 和 业 务 流 程 — — 却 有 可 能 随 着 时 间 而 改 变 。 结 论 结 论 关 于 如 何 正 确 地 写 好 代 码 注 释 ， 简 单 地 搜 一 下 的 话 ， 网 上 有 很 多 很 多 。 有 些 甚 至 可 能 会 告 诉 你 如 何 尽 可 能 地 不 在 代 码 中 提 供 注 释 。 相 反 ， 我 想 分 享 一 些 我 有 幸 作 为 一 个 应 用 程 序 开 发 人 员 所 读 过 的 一 些 滑 稽 的 注 释 。 请 记 住 ， 我 在 应 用 程 序 开 发 上 有 着 2 0 年 以 上 的 编 译 经 验 — — 反 映 了 例 外 ， 而 不 是 规 则 。 编 码 快 乐 ！ 编 译 自 ： h t t p s : / / d z o n e . c o m / a r t i c l e s / m y - c o m m e n t a r y - o n - c o d e - c o m m e n t s   作 者 ：   J o h n   V e s t e r 转 载 自 ： 码 农 网   h t t p : / / w w w . c o d e c e o . c o m / a r t i c l e / 8 - u s e l e s s - c o d e - c o m m e n t i n g . h t m l   译 者 ：   小 峰 推 荐 文 章 推 荐 文 章 I D 点 击 标 题 或 输 入 文 章   I D   直 达 该 文 章 1 一 起 来 说   V i m   语 4 9 3 我 2 年 学 习 编 程 的 经 验 总 结 3 3 7 6 开 源 的 力 量 3 4 1 6 R u b y   o n   R a i l s   发 明 人 的 告 白 ： 当 我 变 成 百 万 富 翁 的 那 天 ， 我 得 到 了 什 么 呢 ？ 3 5 3 5 A t o m   插 件 ： 让 初 音 女 神 来 鼓 励 你 撸 码 将 文 章 分 享 给 朋 友 是 对 我 们 最 好 的 赞 赏 ！ 阅 读 原 文 1 5 .   * /
回复

举报

高级模式
B Color Image Link Quote Code Smilies
您需要登录后才可以回帖 登录 | 立即注册

本版积分规则

使用Markdown编辑器编辑 使用富文本编辑器编辑

Archiver| 手机版| 小黑屋|
Powered by Discuz! X3.4 Copyright © 2001-2020, Tencent Cloud. 商业源码建议获取授权，如侵犯您的权益，请联系客服处理