주석을 달다

모두가 주석을 쓴 적이 있을 것이다. 주석이라는 것은 코드와 다르고 프로그램 논리의 정확성과 직접적인 관계가 없기 때문에 모든 사람은 자신의 스타일이 있을 수 있다. 모든 사람은 어디에 주석을 써야 하는지, 주석을 어떤 모양으로 써야 하는지에 대해 자신의 이해가 있을 수 있다.
나는 개인적으로 주석에 대한 이해는 네 단계를 거쳤다.
첫 번째 단계는 주석을 전혀 쓰지 않고 이 단계는 코드 논리의 실현에 있어 많은 시간을 들여 디버깅을 하고 코드를 수정하기 때문에 주석에 신경 쓸 겨를이 없다.시간이 지나자 전에 쓴 구리고 긴 코드가 전혀 보이지 않자 주석의 중요성을 깨닫고 서서히 두 번째 단계로 접어들기 시작했다.
두 번째 단계는 어디에나 주석이 있고 모든 파일, 모든 종류, 모든 함수, 모든 지점을 설정하고 변수마다 주석이 있어서 설명한다. 작은 세부 사항을 빠뜨려서 이해하지 못할까 봐.나중에 문서 주석이라는 것(doxygen)이 발견됐어요. 이 물건은 너무 멋있지 않아요. 당신이 쓴 주석에 따라 문서를 직접 생성할 수 있어요. 그래서 곳곳에 문서 주석이 있어요. 파일마다 프로필이 있어요. 프로필에서 가장 중요한 내용은 @author: hatlonely예요. 이런 low 코드가 당신이 쓴 것인지 남들이 모를까봐?‍♀️,모든 함수 매개 변수, 함수 매개 변수의 반환값 등도 상세한 주석이 있는데 주석의 길이는 코드의 길이를 훨씬 초과했다.보아하니 엄마는 내가 전에 쓴 코드를 이해하지 못할까 봐 더 이상 걱정할 필요가 없을 것 같다. 그러나 한동안 내가dd라는 함수의 주석을 다시 읽었을 때 나는 이 정보들이 나에게 쓸모가 없는 것 같았다. 이 코드는 이미 충분하고 간단했다. 심지어 주석보다 더 쉽게 읽을 수 있었다. 그러면 이 주석이 여기에 존재하는 의미는 무엇일까. 단지 문서의 주석을 만들기 위해서였을까?더 큰 문제는 내가 함수를 추가하려면 add3(int a, int b, int c) 나는 이전의 문서 주석 형식에 따라 많은 주석을 써야 한다는 것이다. 주석의 유지 보수도 큰 문제이다. 매번 논리가 바뀔 때마다 대응하는 주석을 고쳐야 한다. 수정을 잊어버리면 주석과 코드 논리의 불일치가 더욱 곤혹스러울 것이다.그래서 주석의 유지보수는 매우 무료한 일이 되어 프로그래밍 체험을 크게 낮추었고 다른 한편, 지루하고 번잡한 주석도 코드의 읽기 체험을 낮추었다.

// @file:     .md
// @date: 2018-01-19 14:00
// @author: hatlonely
// @brief:         

// @brief:        
// @param a   
// @param b    
// @return  
int add(int a, int b) {
    return a + b;
}

세 번째 단계는 코드가 주석이다.어느 날, 코드는 예술이고 그 자체가 아름다움이라는 관점을 보았습니다. 마치 시와 같습니다. 한 수의 시에 많은 주석이 삽입된 것을 본 적이 있습니까?주석은 코드에 대한 번역이 아니라 절대 다수의 경우 한 주석으로 변수를 해석하는 것을 고려할 때 좋은 변수 이름을 통해 이 주석을 피할 수 있다. 마찬가지로 특정한 단락의 논리를 주석하려고 할 때도 이 논리 구조를 최적화하고 읽을 수 있는 더 강한 변수를 사용하여 특정한 과정을 묘사할 수 있다.그래서 저는 모든 주석을 없애고 읽을 수 있는 코드를 작성하기 시작했습니다. 모든 일반적인 작은 변수의 이름을 얽매이기 시작했고 일반인의 관점에서 코드의 논리를 생각하기 시작했습니다. 코드가 자연 언어에 더욱 가깝고 어떠한 컴퓨터 기반도 없는 사람들이 제 코드를 읽을 수 있도록 하는 것을 목표로 했습니다.그래서 지금은 코드가 많이 깔끔해졌어요. 코드가 이렇게 간단했어야 했어요.근데 저 마음에 들어요?아니요.
네 번째 단계, 필요한 주석.코드는 시가 아니기 때문에 당시의 문화적 배경과 다른 사람의 해석이 없었다면 대부분 시가 일반인들도 읽을 수 없었을 것이다.코드 논리는 특정한 장면에 의해 결정되고 같은 코드가 서로 다른 장면 아래에서도 완전히 다른 의미를 가진다. 그래서 왜 이런 논리가 이 장면에서 특정한 배경에 의해 결정되는지 코드 자체는 이러한 배경 정보를 포함할 수 없다.예를 들어 아래의 코드, ios 필터에 관한 이 논리는 현재의 업무상 아직 이런 수요가 결정되지 않았기 때문이다. 이곳의 주석은 우리에게 추가 정보를 주었기 때문에 이 논리를 이해하는 데 큰 도움이 된다. 만약에 이 주석이 없다면 한 달 후에 당신은 왜 ios와 같은 특수한 논리가 있는지 잊어버릴 수도 있다. 꼼짝도 못하고 모를 것이다.오랫동안 이 코드들은 수수께끼 같은 존재가 되었다.응, 우아해 보여, 이제 만족해!

func checkDeviceType(info DeviceInfo, deviceTypeSet map[int32]struct{}) bool {
    // ios       android   ，         
    if info.platform != "ios" {
        return true
    }

    if _, ok := deviceTypeSet[info.deviceType]; ok {
        return true
    }
    return false
}

다음 단계는 뭘까요?자신의 표현 능력을 향상시킬 때가 되었다.
전재는 출처 본문 링크를 명기해 주십시오.http://hatlonely.github.io/20...