Comments

Comments

1. 코드의 단위적 로직이 복잡한 것들 (Business logic complexity) 만 주석 처리를 하자!

   • 좋은 코드는 그 자체로 이해하기 쉬우므로, 주석은 복잡한 코드에 대한 사과와 같다.

   Business Logic Complexity

   Many organizations adopt software to support their business process and business logic is embedded in their system.

   To solve this problem we define business logic complexity to capture business logic from the source code and to quantify how hard it is to understand.

   // bad
   function hashIt(data) {
     // The hash
     let hash = 0;
   
     // Length of string
     const length = data.length;
   
     // Loop through every character in data
     for (let i = 0; i < length; i++) {
       // Get character code.
       const char = data.charCodeAt(i);
       // Make the hash
       hash = (hash << 5) - hash + char;
       // Convert to 32-bit integer
       hash &= hash;
     }
   }
   
   // good
   function hashIt(data) {
     let hash = 0;
     const length = data.length;
   
     for (let i = 0; i < length; i++) {
       const char = data.charCodeAt(i);
       hash = (hash << 5) - hash + char;
   
       // Convert to 32-bit integer
       hash &= hash;
     }
   }

2. 주석 처리된 코드를 codebase에 남겨놓지 말고 지워버리기!

   • 형상 관리 툴 (버전 관리; version control) 이 이런 코드들을 남겨놓기 위함이니, 오래된 코드는 옛 버전에 남겨놓자.

   // bad
   doStuff();
   // doOtherStuff();
   // doSomeMoreStuff();
   // doSoMuchStuff();
   
   // good
   doStuff();

3. 기록용 주석은 사용하지 말자

   • 위와 동일하게, 형상 관리 툴 (git : git log 를 통해 이전 버전들 확인) 을 이용하고 필요없는 주석은 모두 날려버리자.

   // bad
   /**
    * 2016-12-20: Removed monads, didn't understand them (RM)
    * 2016-10-01: Improved using special monads (JP)
    * 2016-02-03: Removed type-checking (LI)
    * 2015-03-14: Added combine with type-checking (JR)
    */
   function combine(a, b) {
     return a + b;
   }
   
   // good
   function combine(a, b) {
     return a + b;
   }

4. 위치 표시 주석도 피하자!

   • 적절한 indentation, 함수명 및 변수명 , 포맷팅 을 이용한다면 기능 구분을 위한 정신없는 positional marker comments 는 필요하지 않다.

   // bad
   ////////////////////////////////////////////////////////////////////////////////
   // Scope Model Instantiation
   ////////////////////////////////////////////////////////////////////////////////
   $scope.model = {
     menu: "foo",
     nav: "bar"
   };
   
   ////////////////////////////////////////////////////////////////////////////////
   // Action setup
   ////////////////////////////////////////////////////////////////////////////////
   const actions = function() {
     // ...
   };
   
   // good
   $scope.model = {
     menu: "foo",
     nav: "bar"
   };
   
   const actions = function() {
     // ...
   };