程序员不爱写注释是多愚蠢的一件事

概述

        在软件开发中，程序员编写代码后往往会被要求添加注释，但是有时候我们会发现某些程序员并不爱写注释。这个习惯不仅让其他开发者难以理解代码，而且也会给自己带来后续维护上的困难。

为什么要写注释

提高代码可读性

        编写代码的目的是为了让计算机能够理解并执行，在这个过程中会用到各种变量和函数。虽然编写出符合语法规则的代码可以通过编译，但是在代码实现完之后，其他开发者需要理解你的实现方法，这时注释就显得非常重要了。如果代码中没有注释，那么其他开发者需要逐行地分析代码才能理解其中的含义，这会非常耗时和费力。

        例如，下面是一个简单的 C++程序：单纯这么看，这不得把后面其他程序员累死，如果我是工作接替者，上一个程序员离职，我看到这样的代码，绝对会骂街

#include <iostream>
#include <fstream>
#include <Windows.h>
using namespace std;
#define SCREEN_WIDTH 80
#define SCREEN_HEIGHT 24
string readFile(string fileName) {
    ifstream file(fileName);
    string content((istreambuf_iterator<char>(file)), istreambuf_iterator<char>());
    return content;
}
void writeFile(string fileName, string content) {
    ofstream file(fileName);
    file << content;
    file.close();
}

void displayScreen(char screenBuffer[SCREEN_HEIGHT][SCREEN_WIDTH]) {
    for (int i = 0; i < SCREEN_HEIGHT; i++) {
        for (int j = 0; j < SCREEN_WIDTH; j++) {
            cout << screenBuffer[i][j];
        }
        cout << endl;
    }
}

int main() {
    char screenBuffer[SCREEN_HEIGHT][SCREEN_WIDTH];
    memset(screenBuffer, ' ', SCREEN_HEIGHT * SCREEN_WIDTH);
    int cursorRow = 0;
    int cursorCol = 0;
    string fileName = "code.txt";

    while (true) {
        for (int i = 0; i < SCREEN_HEIGHT; i++) {
            memset(screenBuffer[i], ' ', SCREEN_WIDTH);
        }
        screenBuffer[cursorRow][cursorCol] = '_';
        string fileContent = readFile(fileName);
        int startLine = max(0, cursorRow - SCREEN_HEIGHT + 1);
        int endLine = min((int)fileContent.length() / SCREEN_WIDTH + 1, startLine + SCREEN_HEIGHT);
        for (int i = startLine; i < endLine; i++) {
            for (int j = 0; j < SCREEN_WIDTH; j++) {
                if (i * SCREEN_WIDTH + j < fileContent.length()) {
                    screenBuffer[i - startLine][j] = fileContent[i * SCREEN_WIDTH + j];
                }
            }
        }
        system("cls");
        displayScreen(screenBuffer);
        int ch = _getch();
        switch (ch) {
        case '\r':
            if (cursorRow + 1 < SCREEN_HEIGHT) {
                cursorRow++;
            }
            cursorCol = 0;
            break;
        case '\b': 
            if (cursorCol > 0) {
                cursorCol--;
            }
            else if (cursorRow > 0) {
                cursorRow--;
                cursorCol = SCREEN_WIDTH - 1;
            }
            fileContent.erase(cursorRow * SCREEN_WIDTH + cursorCol, 1);
            break;
        case 0xE0:
            ch = _getch();
            switch (ch) {
            case 75: 
                if (cursorCol > 0) {
                    cursorCol--;
                }
                else if (cursorRow > 0) {
                    cursorRow--;
                    cursorCol = SCREEN_WIDTH - 1;
                }
                break;
            case 77:
                if (cursorCol + 1 < SCREEN_WIDTH) {
                    cursorCol++;
                }
                else if (cursorRow + 1 < SCREEN_HEIGHT) {
                    cursorRow++;
                    cursorCol = 0;
                }
                break;
            case 72:
                if (cursorRow > 0) {
                    cursorRow--;
                }
                break;
            case 80:
                if (cursorRow + 1 < SCREEN_HEIGHT) {
                    cursorRow++;
                }
                break;
            case 71: 
                cursorCol = 0;
                break;
            case 79: // End键
                cursorCol = SCREEN_WIDTH - 1;
                break;
            }
            break;
        default: 
            if (cursorCol + 1 < SCREEN_WIDTH) {
                cursorCol++;
            }
            else if (cursorRow + 1 < SCREEN_HEIGHT) {
                cursorRow++;
                cursorCol = 0;
            }
            fileContent.insert(cursorRow * SCREEN_WIDTH + cursorCol, 1, (char)ch);
            break;
        }
        writeFile(fileName, fileContent);
    }
    return 0;
}

        虽然这段代码非常简单，但是如果没有注释，其他开发者可能不知道这个函数的输入参数和输出结果是什么。如果添加注释，其他程序员的开发效率即可大幅度提升

#include <iostream>
#include <fstream>
#include <Windows.h>

using namespace std;

// 窗口大小
#define SCREEN_WIDTH 80
#define SCREEN_HEIGHT 24

// 读取文件数据
string readFile(string fileName) {
    ifstream file(fileName);
    string content((istreambuf_iterator<char>(file)), istreambuf_iterator<char>());
    return content;
}

// 写入文件数据
void writeFile(string fileName, string content) {
    ofstream file(fileName);
    file << content;
    file.close();
}

// 显示窗口内容
void displayScreen(char screenBuffer[SCREEN_HEIGHT][SCREEN_WIDTH]) {
    for (int i = 0; i < SCREEN_HEIGHT; i++) {
        for (int j = 0; j < SCREEN_WIDTH; j++) {
            cout << screenBuffer[i][j];
        }
        cout << endl;
    }
}

int main() {

    // 窗口缓冲区
    char screenBuffer[SCREEN_HEIGHT][SCREEN_WIDTH];
    memset(screenBuffer, ' ', SCREEN_HEIGHT * SCREEN_WIDTH);

    // 当前光标位置
    int cursorRow = 0;
    int cursorCol = 0;

    // 文件名
    string fileName = "code.txt";

    while (true) {
        // 更新窗口内容
        for (int i = 0; i < SCREEN_HEIGHT; i++) {
            memset(screenBuffer[i], ' ', SCREEN_WIDTH);
        }
        // 显示光标
        screenBuffer[cursorRow][cursorCol] = '_';
        // 读取文件内容并显示
        string fileContent = readFile(fileName);
        int startLine = max(0, cursorRow - SCREEN_HEIGHT + 1);
        int endLine = min((int)fileContent.length() / SCREEN_WIDTH + 1, startLine + SCREEN_HEIGHT);
        for (int i = startLine; i < endLine; i++) {
            for (int j = 0; j < SCREEN_WIDTH; j++) {
                if (i * SCREEN_WIDTH + j < fileContent.length()) {
                    screenBuffer[i - startLine][j] = fileContent[i * SCREEN_WIDTH + j];
                }
            }
        }
        // 显示窗口内容
        system("cls");
        displayScreen(screenBuffer);

        // 处理用户输入
        int ch = _getch();
        switch (ch) {
        case '\r': // 回车键，换行
            if (cursorRow + 1 < SCREEN_HEIGHT) {
                cursorRow++;
            }
            cursorCol = 0;
            break;
        case '\b': // 退格键，删除前一个字符
            if (cursorCol > 0) {
                cursorCol--;
            }
            else if (cursorRow > 0) {
                cursorRow--;
                cursorCol = SCREEN_WIDTH - 1;
            }
            fileContent.erase(cursorRow * SCREEN_WIDTH + cursorCol, 1);
            break;
        case 0xE0: // 方向键、Home、End等键，需要读取下一个字符
            ch = _getch();
            switch (ch) {
            case 75: // 左箭头键
                if (cursorCol > 0) {
                    cursorCol--;
                }
                else if (cursorRow > 0) {
                    cursorRow--;
                    cursorCol = SCREEN_WIDTH - 1;
                }
                break;
            case 77: // 右箭头键
                if (cursorCol + 1 < SCREEN_WIDTH) {
                    cursorCol++;
                }
                else if (cursorRow + 1 < SCREEN_HEIGHT) {
                    cursorRow++;
                    cursorCol = 0;
                }
                break;
            case 72: // 上箭头键
                if (cursorRow > 0) {
                    cursorRow--;
                }
                break;
            case 80: // 下箭头键
                if (cursorRow + 1 < SCREEN_HEIGHT) {
                    cursorRow++;
                }
                break;
            case 71: // Home键
                cursorCol = 0;
                break;
            case 79: // End键
                cursorCol = SCREEN_WIDTH - 1;
                break;
            }
            break;
        default: // 普通字符，插入到当前光标位置
            if (cursorCol + 1 < SCREEN_WIDTH) {
                cursorCol++;
            }
            else if (cursorRow + 1 < SCREEN_HEIGHT) {
                cursorRow++;
                cursorCol = 0;
            }
            fileContent.insert(cursorRow * SCREEN_WIDTH + cursorCol, 1, (char)ch);
            break;
        }

        // 将文件内容写入到文件中
        writeFile(fileName, fileContent);
    }
    return 0;
}

这样其他开发者只需要看函数的注释就可以理解函数的作用和输入输出。

方便代码维护

        在开发过程中，我们会不断地修改代码。如果代码中没有注释，那么在修改代码时就需要重新理解代码的实现过程，这会非常耗时耗力。而如果我们在编写代码的同时添加注释，那么在以后需要进行修改时就可以更加容易地理解代码。这也是为什么我们经常说“好的代码像一篇好的文章，能够让读者轻松理解作者的意图”。

提高代码可维护性

        在软件开发中，存在很多代码需要多人协作完成。如果代码中没有注释，那么其他开发者就很难看懂你的代码，这会造成沟通上的障碍。而如果代码中有注释，就会使得合作更加高效，大家能够更好地理解代码。

注释应该写什么

        注释的目的是为了让其他开发者更好地理解代码，因此我们在编写注释时应该关注以下几个方面：

代码的作用

        注释应该清晰地说明代码的作用，让其他开发者明白你接下来的代码是做什么用的。这是注释中最重要的内容，因为这能够帮助其他开发者快速理解代码的意图。

输入输出

        尤其是对于函数而言，注释应该清晰地说明输入和输出的数据类型、数据格式等信息，使得其他开发者能够更加清晰地理解函数的输入和输出。

扫描二维码关注公众号，回复： 17271863 查看本文章

变量的含义

        注释应该清晰地说明变量的含义和所代表的数据类型。这有助于其他开发者理解变量的作用和代码的逻辑结构。

个别程序员不写注释的原因

1. 时间和压力：在项目开发中，开发周期可能很紧凑，程序员需要快速编写代码并满足需求。写注释可能被视为浪费时间，会降低编码速度。

2. 自我理解：有些程序员对自己写的代码非常了解，他们认为代码本身就应该是自解释的，不需要额外的注释来解释代码的含义。

3. 维护困难：注释可能会引入额外的维护负担。当代码发生改动时，如果注释没有及时更新，就会与实际代码不匹配，从而导致误导和混乱。

4. 注释冗余：有时候注释可能会变得过于冗长，并且与代码逻辑重复。这种情况下，注释可能会造成阅读上的负担，而非帮助。

总结

        注释是编写高质量、易于维护的代码必不可少的一环。添加注释可以提高代码可读性、方便代码维护和提高代码可维护性。在编写注释时，我们应该清晰地说明代码的作用、输入输出以及变量的含义，从而让其他开发者更好地理解代码的实现过程。因此，作为程序员我们应该养成良好的习惯，尽可能地添加注释，让我们的代码更加易于理解和维护。