50个成为优秀程序员的法则[1-10]
原文链接: 50 Coding Laws That Would Make You A Decent Programmer.
1. 不惜一切代价避免注释
开幕暴击，一直以来各种书籍文章或者资料大多建议要写注释，当然我也看到另一种说法不写注释写Wiki，仔细看完作者的观点之后觉得还是挺有道理，作者列举的理由如下:
浏览注释会转移或者分散阅读者的思维
注释可能虚假或者没有及时更新
好的代码无需注释也能看懂
2. 不要使用类型属性作为变量的名称
这个比较好理解，以 Python 为例，作者的建议是通过类型标注来指示变量类型而不是名称。
# ❌
name_of_variable_str = value
# ✅
name_of_variable: str = value3. 类的名称应该是名词
主要是因为类对象用于标识或表示一堆特征和动作，使用名词作为类名会避免冗余，使代码更易读。
# ❌
GetGoat.get_horn_length()
# ✅
Goat.get_horn_length()4. 函数名应该是动词
以便于更好的理解它所进行的操作
5. 函数应该指定参数和返回类型
# ❌
def conver_to_string(num):
return "My new string is " + str(num)
# ✅
def conver_to_string(num: int) -> str:
return "My new string is " + str(num)6. 一个函数必须只能执行一个功能
让一个函数执行一个功能至关重要，因为它有助于暴露错误的位置，实现可重用性，并完全按照函数名称所说的去做。
# ❌
def check_if_address_is_valid(address):
if address.is_valid:
latitude = address.getLatitude()
longtitude = address.getLongitude()
return (latitude, longitude)
# ✅
def check_if_address_is_valid(address):
return address.is_vallid
def get_latitude():
latitude = address.getLatitude()
return latitude
def get_longitude():
longtitude = address.getLongitude()
return longitude7. 函数应该处于相同的抽象级别
指的是一个函数应该执行一个定义明确的任务。该任务应该在整个函数中处于一致的抽象级别。
# ❌
def get_numbers():
numbers = [2,3,4,1,4,1,416,6]
return numbers
def calculate_average():
numbers = get_numbers()
numbers_plus_30 = [num + 30 for num in numbers]
total = sum(numbers_plus_30)
count = len(numbers)
average = total / count
return average
calculate_average()
# ✅
def calculate_average(numbers):
total = sum(numbers)
count = len(numbers)
average = total / count
return average
calculate_average([2,3,4,1,4,1,416,6])
不好的做法的函数有一堆抽象级别。 get_numbers() 是高级抽象，列表理解是中级抽象，sum是低级抽象。
8. 函数名应该与其参数密切相关
# ❌
write(True)
# ✅
write(name)好的做法更能描述函数到底在做什么。
9. 函数应该很小
一个函数应该是可重用的。函数越大，它被重用的可能性就越小。这也与为什么一个函数应该只做一件事相关。如果它只做一件事，它很有可能会很小。
10. 避免冗余的词语
命名应该简洁明了，避免多于的描述，那样反而会导致混淆。
# ❌
getProfileInfo()
getProfileInfos()
getProfileAccount()
# ✅
getProfile()11. 不要成为一个肮脏的程序员
这意味着你要写干净的代码，但什么才是干净的代码呢？干净的代码结构良好，排列良好。干净的代码不会隐藏错误。它向程序员公开了bug可以隐藏的任何地方，并可以无需完全重构就可以修复其中的bug。
12. 开放封闭原则
开放-封闭原则（OCP）指出，类、方法或函数必须对扩展开放，但不能进行修改。这意味着定义的任何类、方法或函数都可以很容易地为多个实例重用或扩展，而无需更改其代码。
13. Liskov替换原则
Liskov替换原则（LSP）是一种子类型关系的特定定义，称为强行为子类型，最初由Barbara Liskov在1987年的一次会议主题演讲中引入，题为数据抽象和层次结构。它基于“可替换性”的概念——面向对象编程中的一项原则，规定对象（如类）可以被子对象（如扩展第一类的类）替换，而不会破坏程序。它是一种语义关系，而不仅仅是句法关系，因为它旨在保证层次结构中类型的语义互操作性，尤其是对象类型。
14. 知道何时使用注释
文章中说，每当您需要使用注释时，都要为自己无法用代码表达自己而感到羞耻。但是在某些情况下，使用注释实际上有助于表达代码的底层工作原理，而不是代码本身。原文列举了几个好注释的最佳示例：
- 信息注释：例如，突出函数返回值的注释
- TODO注释
- 后果警告
15. 什么时候不适合添加注释
-
噪声注释 ，如下：
# add to animal list animal.append(dog) - 非本地信息 ：编写注释时，确保它只与它引用的函数或语句相关。除此之外的任何内容都应该删除。
- 不明显的注释 ：你的评论和引用的函数之间的联系必须清晰。
- 短函数 ：短函数往往不需要注释，而是用一个好的名字来描述它。
16. 保持源文件简短
出于可重用性和易读性的需要，源文件应该在100-200行之间，最多500行。除非你有很好的理由选择其他方式。
17. 正确的使用空行
空行是告诉读者我们正在进入一个新的独立概念的一种方式。每一个代码块表示一个完整的想法。
18. 保持相关联的代码/函数/类靠近
Go where you are valued
函数/变量应该尽可能靠近最需要或最重要的地方。它应该离它最不重要的地方最远。
19. 知道何时使用空白
我们使用空格来表示两件事不是强相关的，没有空格来关联强相关的事物。
20. 遵守团队规则
降低这些个人偏好并采用团队的偏好。