代码中的注释的重要性（二）

周末也要写八哥2026-05-06 16:42

注释与团队

也许看到这里，你会觉得注释好像只是为了让新手更友好的学习，对老手或其他团队成员之间的合作没啥用。其实不然！我们再看看下面这个示例（只是为了讲解注释的作用而举例，实际生活不一定存在）。

示例背景

某公司开发团队目前正在开发一个相对复杂的机器学习项目，这个项目里面包含多个模块和算法的实现。同时，开发团队成员的水平并不一样，此时还有其他项目组的新人调入该项目来共同协作开发。

示例代码（没有注释版）

注意：这个示例仅仅是为了说明注释作用，并不一定代表任何真实的机器学习算法！

复制代码

import numpy as np  
  
def Complex_ML_Algorithm(data, hyper_parameters):  
    """  
    这个函数本来应该有一个文档字符串，但在当前示例中它被省略了  
    来模拟没有注释的情况。
    """  
    processed_data = data / np.max(data, axis=0)  
      
    predictions = np.zeros((data.shape[0], 1))  

    for i in range(data.shape[0]):  
        for j in range(data.shape[1]):  
            if hyper_parameters['feature_selection'] and data[i, j] < hyper_parameters['threshold']:  
                continue  
              
            weighted_sum = 0  
            for k in range(len(hyper_parameters['weights'])):  
                if j == hyper_parameters['weights'][k]['feature_index']:  
                    weighted_sum += hyper_parameters['weights'][k]['weight'] * processed_data[i, j]  
              
            predictions[i, 0] += np.tanh(weighted_sum)  
      
   
    predictions = predictions / data.shape[1]  
      
    return predictions  
    
data = np.random.rand(100, 10)  
hyper_parameters = {  
    'feature_selection': True,  
    'threshold': 0.5,  
    'weights': [  
        {'feature_index': 0, 'weight': 0.2},  
        {'feature_index': 3, 'weight': 0.4},  
       
    ]  
}  
  
predictions = Complex_ML_Algorithm(data, hyper_parameters)  
print(predictions)

如果此时你是新加入这个团队的开发人员，你是不是会迷惑 Complex_ML_Algorithm 函数这样设计（或定义）的目的是什么？其他团队成员也会因为对这个函数复杂的嵌套逻辑表示不解，然后团队之间可能出现沟通障碍，最后甚至出现没有任何人能完全理解这个函数。就更谈不上对这个函数进行修改和拓展，最终也导致项目的进度受阻，项目风险增加。