Typically, comments should be used for three things.
우리는 세 가지 경우에 주석을 사용합니다
First, for a given library, program, or function, comments are best used to describe what the library, program, or function, does.
첫째로, 라이브러리, 프로그램, 함수를 끌어와(혹은 만들어)사용할 때, 그것들의 역할에 대해서 설명하는 주석입니다
These are typically placed at the top of the file or library, or immediately preceding the function. For example:
라이브러리, 혹은 코드의 최 상단, 혹은 함수의 바로 앞에 있으면 좋죠
예를 들어 볼까요? (이번엔 dark mode 가 아닌 light mode 로 갑니다)
// This program calculates the student's final grade based on his test and homework scores.
// 이 프로그램은 학생의 시험 및 과제 점수에 기반하여 학생의 최종 성적을 계산하는 프로그램입니다
// This function uses Newton's method to approximate the root of a given equation.
// 이 함수는 주어진 방정식의 근을 계산하는 뉴턴의 방식을 이용합니다
// The following lines generate a random item based on rarity, level, and a weight factor
// 이 코드 라인은 확률, 레벨, 그리고 가중치에 근거하여 랜덤한 아이템을 생성하는 코드 라인입니다
All of these comments give the reader a good idea of what the library, program, or function is trying to accomplish without having to look at the actual code.
이 주석들을 보면, 코드를 읽는 사람에게 실제 코드를 읽기도 전에 간략히 이 라이브러리가 무엇인지, 이 프로그램 혹은 함수가 무엇인지에 대해서 잘 설명하고 있죠?
The user (possibly someone else, or you if you’re trying to reuse code you’ve previously written) can tell at a glance whether the code is relevant to what he or she is trying to accomplish.
코드의 사용자 (뭐 다른 사람일 수도 있고, 당신이 이전에 작성한 코드를 사용하는 당신 자신일 수도 있지요) 는 '이 코드를 사용해야 하는가?' 라는 판단을 한 눈에 내릴 수 있습니다.
This is particularly important when working as part of a team, where not everybody will be familiar with all of the code.
특히, 해당 코드에 익숙치 않은 팀원들과 함께 팀웍을 하게 될 때, 이는 더더욱 중요합니다.
Second, within a library, program, or function described above, comments can be used to describe how the code is going to accomplish its goal.
둘째로, 라이브러리에서, 프로그램에서, 혹은 함수 '속에서', '어떻게 이 코드가 목적을 달성하는지' 에 대한 과정을 보여줄 수 있는 주석입니다
[ 예시 1]
/* To calculate the final grade, we sum all the weighted midterm and homework scores
최종 성적을 산출하기 위해서, 우리는 모든 중간고사와 과제 점수를 더한 뒤
and then divide by the number of scores to assign a percentage, which is
그 합을 그 점수의 갯수들로 나누어 백분위를 산출합니다,
used to calculate a letter grade.
또 이를 통해 최종 성적을 계산합니다 */
[ 예시 2 ]
// To generate a random item, we're going to do the following:
// 랜덤 아이템을 생성하기 위해서, 우리는 다음고 같은 과정을 거칩니다
// 1) Put all of the items of the desired rarity on a list
// 1) 희망 리스트에서 모든 아이템을 꺼냄
// 2) Calculate a probability for each item based on level and weight factor
// 2) 가중치와 레벨을 활용하여 각 아이템마다의 등장확률을 계산함
// 3) Choose a random number
// 3) 랜덤한 수를 뽑음
// 4) Figure out which item that random number corresponds to
// 4) 어떤 아이템이 그 랜덤한 수와 매칭되는지 구함
// 5) Return the appropriate item
// 5) 그 아이템을 줌
These comments give the user an idea of how the code is going to accomplish its goal without having to understand what each individual line of code does.
이 주석들은 사용자에게 '어떻게 이 코드가 상기한 목적을 달성하는가' 에 대한 과정을, 코드 라인 하나하나를 굳이 읽지 않아도 깔끔하게 알 수 있게끔 해 줍니다.
* 개인적으로 가장 인상깊었던 부분입니다
Third, at the statement level, comments should be used to describe why the code is doing something. A bad statement comment explains what the code is doing.
셋째로, 선언하는 과정에서 (변수 등) 주석은 이 코드가 '왜' 이것을 하는지를 묘사해야지, '무엇을' 하는지에 대해서 묘사하면 안 됩니다
If you ever write code that is so complex that needs a comment to explain what a statement is doing, you probably need to rewrite your statement, not comment it.
당신이 코드를 작성할 때, 이 선언이 '무엇을' 하는 지에 대해서 주석을 달아야 하나 말아야 하나, 고민한다면
코드를 다시 쓰십시오, 주석은 달지 마시구요
Here are some examples of bad line comments and good statement comments.
좋은 예시('왜' 이렇게 선언했는지에 대한 주석) 과 좋지 않은 예시('무엇을' 하는지를 선언하는 데 설명한 주석) 을 보여드리겠습니다
[ 좋지 않은 주석 : 1번 ]
// Set sight range to 0
// 시야를 0으로 만듭니다
sight = 0;
> 좋지 않은 이유 : sight 가 0이라고 선언된 건 코드에서도 확인할 수 있는데, 굳이 주석을 달아놨군요
[ 좋은 주석 : 1번 ]
// The player just drank a potion of blindness and can not see anything
// 플레이어가 눈을 멀게 하는 물약을 먹어서 아무 것도 보이지 않습니다
sight = 0;> 좋은 이유 : 우리가 '왜' 플레이어의 시야가 0이 되었는지를 이 주석을 통해 알 수 있게 되었으니깐요
[ 좋지 않은 주석 : 2번 ]
// Calculate the cost of the items
// 모든 아이템의 값을 계산합니다
cost = quantity * 2 * storePrice;> 좋지 않은 이유 : 가격이 이렇게 나오는 건 알겠는데, 2를 어째서 곱하는 지에 대해선 설명이 나와있질 않네요
[ 좋은 주석 : 2번 ]
// We need to multiply quantity by 2 here because they are bought in pairs
// 아이템을 2개 - 1묶음 단위로 구매하기 때문에, *2를 해 줍니다
cost = quantity * 2 * storePrice;> 좋은 이유 : 왜 이런 식이 나오는 지에 대해서 알 수 있습니다
Programmers often have to make a tough decision between solving a problem one way, or solving it another way.
개발자들은 종종 이 방법으로 풀어야 하는지, 혹은 다른 방법으로 풀어야 하는지 고민할 때가 있습니다
Comments are a great way to remind yourself (or tell somebody else) the reason you made one decision instead of another.
그런 의미에서 주석은 당신에게, 혹은 다른 누군가에게 '내가 이 방법으로 문제를 푼 이유' 에 대해서 설명해 주는, 가장 좋은 방법이지요
요약하자면, 다음과 같습니다
1. 라이브러리, 프로그램, 혹은 함수를 땡겨 쓸 때, '이게 무엇인가' 에 대해서 주석을 달아주세요
2. 라이브러리, 프로그램, 함수 안에서, '어떻게 이것이 목표한 바를 이루는가' 에 대한, 방법에 대한 주석을 달아주세요
3. 무언가를 선언할 때, '왜' 이것을 하는지를 말해주세요
주석에 대해 고민하던 도중 참으로 좋은 글을 발견해 번역해 봤습니다
* 출처 : https://www.learncpp.com/cpp-tutorial/comments/
1.2 — Comments | Learn C++
1.2 — Comments By Alex on May 30th, 2007 | last modified by Alex on May 1st, 2020 A comment is a programmer-readable note that is inserted directly into the source code of the program. Comments are ignored by the compiler and are for the programmer’s u
www.learncpp.com