以下是根据本鲁码农自己的经验，绝大部份参考Clean Code这本书，我自己是将这本书奉为
圭臬，不过我也知道很多人反对书里的一些看法，所以听听就好
首先一个最大的原则就是程式码必须好懂，因为它同时是写给机器跟人看的，好懂是可扩充
性跟可维护性的必要，是程式码无比重要的基石
推文有人说程式码没有注解的话十年后的自己会无法理解，实际上根据我自己的经验如果我
写出一段不好读的程式码，几天、几个小时甚至几分钟之后我就会痛恨之前的自己了
那么注解是必要的吗？我认为注解有其必要，但应该越少越好
为什么越少越好呢？首先，程式码应该要可以自己描述自己，来看一个简单的范例：
float multi(float a, float b) {
return a*b;
}
很容易就能看出这是一个做乘法的方法，但他的用处是什么？没人看得出来
float convertUsdToNtd(float usd, float converRatio) {
return usd * convertRatio;
}
这样就一目了然了，这是一个把美金转换成新台币的方法，如此就不需要注解了。在实务上
，尤其是在有复杂的业务逻辑的时候，变量跟方法名称可能会长到恼人的地步，但为了可读
性，这是必要的牺牲。
我们还能继续扩充这个方法，例如说加入即时汇率，让他可以将转换币值这件事做的更好
float convertUsdToNtd(float usd, FinaceService financeService) {
return usd * finaceService.getUsdToNtdRatio; // Multiply usd and ratio.
}
上面的程式码有一行注解，但不难看出这个注解是一句废话，因为他只是描述了该句程式码
做了什么。好的注解应该从抽象、高层次的方向来解释程式码的用意、为什么要这么写：
float convertUsdToNtd(float usd, FinaceService financeService) {
// Fetch ratio from finance service for real time
return usd * finaceService.getUsdToNtdRatio;
}
上面的程式码解释了为什么要从finance service 获得汇率，因为必须要获得当下即时的汇
率
但注解并不总是好的，有时候他可能是有害的。假设我今天修改了这个方法，让他不再是根
据即时汇率，而是某一天的平均汇率：
float convertUsdToNtdByDate(float usd, Date date, FinaceService financeService)
{
// Fetch ratio from finance service for real time
return usd * finaceService.getUsdToNtdRatioByDate(date);
}
程式码更改但是注解忘了更新的情况下，这行注解就是错的。错误的注解会造成混乱，低效
，甚至错误！程式码本身的可读性重要性应该永远高于注解，因为程式码描述的就是事实，
你没办法写出一行程式码做的事情和他看起来的不同（Well, 通常没办法）但是注解可以！
跟注解不同的是，我认为文件（document）是有必要而且多一点较好的，文件是写在方法前
面的注解，用来描述这个方法做了什么：
/*
Convert USD to NTD by ratio from a specific date.
*/
float convertUsdToNtdByDate(float usd, Date date, FinaceService financeService)
{
return usd * finaceService.getUsdToNtdRatioByDate(date);
}
文件是让下一份阅读程式码的人（通常就是你自己）快速理解这个方法是做什么，他会输入
什么，他会回传什么最好的方式。文件只会从最抽象的层次描述方法，不会包含任何的实作
细节，除非这个细节有必要让使用者知道（例如说，某些情况下的算法和其时间复杂度）
。而且我认为应该要采用文件导向的方式-当你创建新的方法时，你应该先编写文件修改时
亦同
※ 引述《ianlin1216 (伊恩可可)》之铭言
: 饿死抬头
: https://i.imgur.com/3QcIsVN.jpeg
: 本鲁不是资工系的啦
: 所以不知道写程式不加注解会有多严重
: 想请问相关从业的乡民
: 实务上遇到这种情况真的很赌烂吗
: 干五西恰

首先算钱用浮点

反对者很多 而且还很大一部份是不学无术的老屁股冗员因为写clean code很麻烦 很烧脑 很吃力不讨好 懒啦

原来写在 function 前的comment还有特别称呼啊XD

西洽点在哪

所以是建议用大写区隔函式内的词而不是底线吗

我知道算钱有更好的方式，但我不想加入太多东西让这篇文章对新手来说更难懂

推文件导向

回文不用点

回文不是不用点 而是没有洽点的话要跟引文有关系

命名风格通常是根据程式语言跟你的团队来做决定，以这篇文来说是Java

这篇显然是跟引文有关的

回文又不用点 鬼叫什么

前面的那个不完全是comment，有的说法是doc string。像是Python有"""开头"""结尾可以写整串的东西能用。

总之好懂的写法就是对的，想办法写出好懂的程式也是对的

我一直以为这些都叫做 comment XDDD

这篇是正确的，可以自我注释的程式码才好读

Rust有///开头的东西，编译同时可以输出成文件。

推这篇

我现在常常只写注解就让GenAI跑程式出来

如果函数切分得好，函数名称本身就是一个好的注解了。

算钱也不能用浮点，用decimal才能避免小数点问题

很多语言甚至不同TEAM的规范都不同吧 这我倒是觉得统一就好

大写区隔函式内的词??你是想说 camel case ??

每个语言基本代码风格规范不同这看起来是C#

这是JAVA阿

C/C++ 是不是也是这个样子啊？

真的欸 那他在说什么大写

C#的命名风格是函数PascalCase，区域变量才用camelCase。

这个变量命名那个自己组里面讲好就好了 然后写的时候看一下有没有跟旁边的code长得太不一样XDDD

推文应该只是不知道code style，那个各语言习惯差很多。

反正不要用奇怪的缩写或没意义的词就好有看过初学者用ABCDEFG来命名XD

editorconfig解决缩排问题，coding style各语言各有工具。

现在写程式比以前好太多了，AI太强

听说打竞赛的为了拼那几秒，会用abc跟ijk这种免洗命名法XD

变量名不要取太差就还好 真的

https://i.imgur.com/QdO4bqq.png有些26会用汉语拼音+缩写=通灵命名法

y1s1 对岸应该很习惯

我一直想知道中国工程师写int64会不会过不了审

不会 小学生看不懂

26那边真的很多拼音缩写的智障命名法= =

变量如何命名也是个大坑，一般来说你的视野（scope）越大，名称就要越长，反之则最短

5楼菜鸡还特别大声

所以一般会用namespace保护啊

但C没有namespace，不是在.c能用static藏的函数得很臭长。

没有 namespace ... 好ㄅ

原来如此

其实大家指的“必须要存在的” comment 就是原 Po 的 document 吧只是好像不是每个人都会这样称呼它，甚至我也只在 cleancode 以及一些软工讨论才有机会看到这样的称呼C 因为没有 namespace 所以 scope 更显得重要就是了。幸好还是有 struct 这种基本的能用

VS有内建的注解系统能搭配PLUGIN输出成程式说明文件但认真写会变成CODE以外一大堆又臭又长的XML注解 所以官方又建议你用另一个特殊的XML NODE把整份XML注解移动到一个独立的XML档案 然后程式码只要指过去就好 但不知道有多少人真的有用这套XML注解功能产整份文件...

推 clean code

对，你全部都重写当然没问题

推

我自己经验，一个礼拜这只code就不认识了，有过看code觉得这个人写的不错，想法和我差不多，再看作者，靠北，不就是我自己，还上礼拜写的 XD 忙的时候特别容易发生这种事情

现代萤幕都够大了取名长一点没什么问题 取很简短又重复的在大型专案里面搜关键字会很火

推

同意这篇

算钱用浮点 迟早被人扁

同意文件的优先重要性但如果遇到写文件就像要他命的团队...摸摸鼻子写好ITS备注跟注解存证据比较快= =

c 姑且算是有 ns 啦 只是人家的 ns 是划在 compile unit 上

推推

所以会有那种同一个元件有两个 header 一个内用一个外带

clean code 明明就蛮简单的 讲白了用代码讲清楚自己的代码在干嘛

文件跟注解有一样的问题 程式码改了 功能有变化 文件不见得会更新 是说连注解都没改了 文件更不会改但是写文件跟维护文件很重要我举双手同意只是时程上往往没有足够的时间去维护文件

推这篇 没有code review已经够怪了 连规范都没有 不知道那种公司在干嘛