[개발] 코딩 규칙

 

 

[개발] 코딩 규칙

 

 

 

1.   명명규칙과 표준

 

참고 : 이 문서에는 파스칼 케이싱(Pascal casing)과 캐멀 케이싱(Camel casing)이란 용어를 사용한다. 파스칼 케이싱 - 단어의 첫번째 글자는 모두 대문자, 나머지는 모두 소문자. 예: BackColor 캐멀 케이싱 - 맨 첫번째 단어를 제외한 단어의 첫번째 글자는 대문자, 나머지는 모두 소문자. (역주 : 두 번째 단어부터 대문자라서 낙타 등처럼 중간부분이 볼록해서 캐멀(낙타)케이싱 이라고 한다.) 예: backColor

 

1.   클래스명 : 파스칼 케이싱

 

public class HelloWorld

{

...

}

 

2.   메소드명 : 파스칼 케이싱

 

void SayHello(string name)

{

...

}

 

 

3.   메소드인자, 변수 : 캐멀 케이싱

 

int totalCount = 0;

void SayHello(string name)

{

string fullMessage = "Hello " + name;

...

}

 

4.   인터페이스 : 'I' + 파스칼 케이싱 ( 예: IEntity )

 

5.   변수명에 대해 헝가리안 표기법을 사용하지 말라

 

좋지 않은 예:

string m_sName;

int nAge;

 

헝가리안 표기법은 타입이 엄격하게 지켜지지 않는 언어에 대해 유용하였으나, 닷넷의 경우 타입검사가 엄격하고, 개발 툴 자체에서 타입에 대해 쉽게 알아 볼 수 있기 때문에 헝가리안 표기법을 따르지 말 것을 권고한다.

 

 

 

일부 프로그래머들은 여전히 m_ 를 통해 멤버변수를 구분하는 네이밍을 선호하는데, 이는 현재 지역변수와 멤버변수를 구분하기에 편하고 마땅한 대한도 없다.

 

 

6.   변수에 의미를 부여하라. 축약하지 말라.

 

좋은 예:

 

string address

int salary

 

 

좋지 않은 예:

 

string nam

string addr

int sal

 

 

7.   i, n, s 와 같은 한 글자로 이루어진 변수를 사용하지 말라.

 

다만 다음은 예외로 한다:

 

for ( int i = 0; i < count; i++ )

{

...

}

 

위와 같은 곳에서 i는 아주 오랫동안 관습처럼 쓰여왔고, 다른 곳에서 사용하지 않는다면 허용한다.

 

 

8.   지역변수에 언더스코어( _ ) 문자를 사용하지 말라.

 

 

9.   멤버변수는 언더스코어( _ )로 시작하여 지역변수와 구분하라.

 

 

10.  변수명을 예약어와 유사하게 사용하지 말라.

 

 

11.  불린 값을 리턴 하는 메소드, 프러퍼티, 변수는 'is' 접두어를 붙여라.

 

Ex: private bool _isFinished

 

 

12.  네임스페이스는 아래와 같은 규칙으로 작성하라

 

<회사명>.<제품명>.<상위모듈>.<하위모듈>

 

 

13.  UI 를 구성요소에 대해서 알맞은 접두어를 붙여서 다른 변수와 구분하라.

 

이 문서에서 추천하는 방법은 아래 두 가지다.

 

a.   ( ui_ ) 와 같은 접두어로 통일하여 붙여준다. 이 방법은 인텔리센스에서 UI구성요소만 리스트업하기에 좋다.

 

b.   각 UI 구성요소에 해당하는 약어를 접두어로 붙인다.

 

 

Control	Prefix
Label	lbl
TextBox	txt
DataGrid	dtg
Button	btn
ImageButton	imb
Hyperlink	hlk
DropDownList	ddl
ListBox	lst
DataList	dtl
Repeater	rep
Checkbox	chk
CheckBoxList	cbl
RadioButton	rdo
RadioButtonList	rbl
Image	img
Panel	pnl
PlaceHolder	phd
Table	tbl
Validators	val

 

 

 

 

14.  파일명은 해당 클래스명으로 사용한다.

 

HelloWorld 클래스는 HelloWorld.cs 파일로 저장한다

 

15.  파일명은 파스칼 케이싱을 사용한다.

 

 

 

2.   들여쓰기, 공백

 

 

1.   공백 말고 TAB으로 들여쓰기 한다. 크기는 4로 한다.

 

2.   주석은 코드와 같은 수준의 들여쓰기에서 작성한다.

 

좋은 예:

 

// Format a message and display

 

string fullMessage = "Hello " + name;

DateTime currentTime = DateTime.Now;

string message = fullMessage + ", the time is : " + currentTime.ToShortTimeString();

MessageBox.Show ( message );

 

좋지 않은 예:

 

// Format a message and display

string fullMessage = "Hello " + name;

DateTime currentTime = DateTime.Now;

string message = fullMessage + ", the time is : " + currentTime.ToShortTimeString();

MessageBox.Show ( message );

 

3.   중괄호({})는 감싸고 있는 밖의 코드와 동일한 레벨에서 작성한다.

 

        

4.   논리적으로 로직이 구분되는 곳에는 빈 줄을 삽입한다

 

좋은 예:

         bool SayHello ( string name )

         {

                  string fullMessage = "Hello " + name;

                  DateTime currentTime = DateTime.Now;

 

                  string message = fullMessage + ", the time is : " + currentTime.ToShortTimeString();

 

                  MessageBox.Show ( message );

 

                  if ( ... )

                  {

                           // Do something

                           // ...

 

                           return false;

                  }

 

                  return true;

         }

 

좋지 않은 예:

 

         bool SayHello (string name)

         {

                  string fullMessage = "Hello " + name;

                  DateTime currentTime = DateTime.Now;

                  string message = fullMessage + ", the time is : " + currentTime.ToShortTimeString();

                  MessageBox.Show ( message );

                  if ( ... )

                  {

                           // Do something

                           // ...

                           return false;

                  }

                  return true;

         }

 

5.   클래스내의 메서드사이의 구분은 빈 줄 하나로만 하라.

 

6.   중괄호는 한 줄을 단독으로 사용하라. (문장의 마지막에 넣지 말라)

 

좋은 예:

                  if ( ... )       

                  {

                           // Do something

                  }

 

좋지 않은 예:

 

                  if ( ... )        {

                           // Do something

                  }

 

7.   공백을 사용하는 명령이나 괄호 등의 구분에는 한 칸의 공백만 사용하라.

 

좋은 예:

                  if ( showResult == true )

                  {

                           for ( int i = 0; i < 10; i++ )

                           {

                                    //

                           }

                  }

 

좋지 않은 예:

 

                  if(showResult==true)

                  {

                           for(int     i= 0;i<10;i++)

                           {

                                    //

                           }

                  }

8.   private 멤버변수, 메서드는 파일의 맨 위에 두고, 그 바로 아래 public 멤버를 작성하라. 

 

 

 

3.   좋은 프로그래밍 습관

 

1.   메서드는 1~25줄 정도로 짧게 작성하라. 길다면 리팩터링을 통해 분리하라.

 

2.   메서드명은 수행하는 이름을 명확히 하여 작성하라. 이렇게 하면 메서드에 대한 주석이 필요 없다.

 

좋은 예:

         void SavePhoneNumber ( string phoneNumber )

         {

                  // Save the phone number.

         }

 

좋지 않은 예:

 

         // This method will save the phone number.

         void SaveDetails ( string phoneNumber )

         {

                  // Save the phone number.

         }

 

3.   아무리 작은 단위의 작업을 하는 메서드라 할지라도 하나의 메서드는 하나의 작업만 하라.

 

좋은 예:

         // Save the address.

         SaveAddress (  address );

        

         // Send an email to the supervisor to inform that the address is updated.

         SendEmail ( address, email );               

        

         void SaveAddress ( string address )

         {

                  // Save the address.

                  // ...

         }

        

         void SendEmail ( string address, string email )

         {

                  // Send an email to inform the supervisor that the address is changed.

                  // ...

         }

 

좋지 않은 예:

 

         // Save address and send an email to the supervisor to inform that

// the address is updated.

         SaveAddress ( address, email );

 

         void SaveAddress ( string address, string email )

         {

                  // Job 1.

                  // Save the address.

                  // ...

 

                  // Job 2.

                  // Send an email to inform the supervisor that the address is changed.

                  // ...

         }

 

4.   System 네임스페이스에 정의된 자료형 대신 C# 에서 사용하도록 Alias 된 자료형을 사용하라.

 

         int age;   (not Int16)

         string name;  (not String)

         object contactInfo; (not Object)

 

        

일부 개발자는 이 방법보다 System 네임스페이스에 있는 자료형 사용을 선호하기도 한다..

 

5.   언제나 예상치 못한 값에 대비하라.

 

좋은 예:

 

If ( memberType == eMemberTypes.Registered )

{

// Registered user… do something…

}

else if ( memberType == eMemberTypes.Guest )

{

// Guest user... do something…

}

else

{

         // Un expected user type. Throw an exception

         throw new Exception (“Un expected value “ + memberType.ToString() + “’.”)

 

         // If we introduce a new user type in future, we can easily find

// the problem here.

}

 

좋지 않은 예:

 

If ( memberType == eMemberTypes.Registered )

{

         // Registered user… do something…

}

else

{

         // Guest user... do something…

 

// If we introduce another user type in future, this code will

// fail and will not be noticed.

}

 

6.   숫자 값을 하드코딩 하지 말라. (대신 readonly, const 을 사용하라).

 

그러나 상수의 사용은 자제하고 필요하다면 데이터베이스나 파일에 기록하여 사용하라. 추후에 수정이 있게 된다면 모든 관련 어셈블리를 다시 빌드해야 한다. (readonly 를 사용하라)

 

 

7.   문자열을 하드코딩 하지 말라. (대신 리소스파일을 사용하라).

 

 

8.   문자열을 비교할 때는 대문자(혹은 소문자)로 변경한 뒤 수행하라. (역주:Equal 메서드의 오버로드중 비교타입에 IgnoreCase 를 설정해도 된다.)

 

if ( name.ToLower() == “john” )

{

    //…

}

 

 

9.   "" 대신에 string.Empty 를 사용하라

 

좋은 예:

 

If ( name == String.Empty )

{

// do something

}

 

좋지 않은 예:

 

If ( name == “” )

{

// do something

}

 

 

10.  멤버 변수의 사용을 자제하라. 여러 메서드에서 사용해야 될 필요가 있는 변수는 메서드의 인자로 전달하는 구조를 사용하라. 멤버 변수를 사용했을 때 오류가 발생(중간에 값이 예기치 않게 변경)하면 어디서 바뀌었는지 찾기 힘들다.

 

11.  열거형(enum) 대신 숫자나 문자열을 사용하지 말라.

 

좋은 예:

         enum MailType

         {

                  Html,

                  PlainText,

                  Attachment

         }

 

         void SendMail (string message, MailType mailType)

         {

                  switch ( mailType )

                  {

                           case MailType.Html:

                                    // Do something

                                    break;

                           case MailType.PlainText:

                                    // Do something

                                    break;

                           case MailType.Attachment:

                                    // Do something

                                    break;

                           default:

                                    // Do something

                                    break;

                  }

         }

 

 

좋지 않은 예:

 

         void SendMail (string message, string mailType)

         {

                  switch ( mailType )

                  {

                           case "Html":

                                    // Do something

                                    break;

                           case "PlainText":

                                    // Do something

                                    break;

                           case "Attachment":

                                    // Do something

                                    break;

                           default:

                                    // Do something

                                    break;

                  }

         }

12.  멤버변수를 public 이나 protected 로 선언하지 말라. private로 선언한 후에 public, protected 프러퍼티로 노출하라.

 

13.  이벤트 핸들러에서 해당 이벤트의 작업을 수행하지 말고, 별도의 메서드를 호출하여 처리하라.

 

14.  클릭과 같은 이벤트 핸들러에서 호출하는 별도의 작업메서드를 직접 호출하지 말라. 필요하다면 해당 이벤트 핸들러를 호출하라.

 

15.  로컬 경로나 드라이브명을 하드코딩 하지 말라.

 

16.  실행경로가 특정한 곳(C:\)일 것이라는 가정하에 코딩 하지 말라

 

17.  어플리케이션이 시작되면 '셀프 체크'를 수행하여 필요한 파일들이 있는지 등을 확인하고 문제가 있다면 사용자에게 친절한 오류메시지를 보여주어라.

 

18.  환경설정파일이 없다면 기본설정의 파일을 만들어 주어라.

 

19.  환경설정파일 등에서 문제가 있는 값이 있다면 문제가 있는 항목과 함께, 어떠한 값이 올바른 값인지를 보여주어라.

 

20.  오류 메시지는 사용자로 하여금 문제해결에 도움을 주는 단서가 된다. '오류가 발생하였습니다.', '어플리케이션 오류' 와 같은 메시지 대신 '데이터베이스 접속에 실패하였습니다. 로그인ID와 비밀번호를 확인하여 주십시오.' 와 같은 메시지를 보여주어라.

 

21.  (20번과 같은 의미라서 생략)

 

22.  사용자에게는 짧지만 친절한 메시지를 보여주되, 실제로는 알 수 있는 모든 정보를 기록한 로그파일을 만들어 두어라. 이는 나중에 디버깅할 때 도움이 된다.

 

23.  하나의 파일에는 하나의 클래스만 작성하라.

 

24.  Visual Studio는 코딩에 대한 템플릿을 작성할 수 있는 기능을 제공해준다. 이를 활용하라.

 

25.  너무 긴 소스를 가지는 클래스를 작성하지 말라. 1000라인 이상이 된다면, 이는 리팩터링 대상으로 좋다. 둘 이상의 클래스로 분할하라.

 

26.  public 메서드나 프러퍼티는 정말 꼭 필요한 곳에서만 사용하고, 만약 동일 어셈블리 내에서만 사용된다면 internal 을 사용하라.

 

27.  메서드에 너무 많은 인자를 넘기지 말라. 4~5개 이상의 인자가 전달되는 메서드가 있다면, 클래스 혹은 메서드의 구조를 재조정하라.

 

28.  컬렉션을 리턴 값으로 가지는 메서드가 있다면, 값이 없는 경우에 null 을 리턴 하지 말고 빈 컬렉션을 넘겨줘라. 리턴 받은 리턴 값을 체크할 때 null 체크를 하지 않고 count만 체크하면 되며, 설사 잊어먹었다 하더라도 null 참조 예외가 발생하지 않는다.

 

29.  버전, 어셈블리에 대한 설명, 회사명, 저작권 정보 등을 AssemblyInfo 파일에 작성해 두어라.

 

30.  프로젝트에 사용하는 파일들은 폴더를 통해 논리적으로 분리하라. 2단계의 계층 구조로 분리하는데, 최상위 폴더는 10개 이하의 폴더를 가지고, 그 하위 폴더는 5개 이하의 폴더를 가지도록 분리하다. 폴더가 너무 많아서 이러한 구조로 분리할 수 없다면, 어셈블리를 별도로 분리하여 파일을 나누도록 하라.

 

31.  좋은 로깅클래스를 작성하라. 로그클래스는 설정하기에 따라 오류메시지만을 기록할 수도 있고, 오류시의 경고나 스택정보와 같은 세부정보를 기록할 수도 있다. 또한 로그 방법을 파일, SQL서버, 윈도우즈 로그 이벤트, 이메일 등으로 작성할 수 있도록 하여 어플리케이션에 맞추어 사용하라. 이는 나중에 오류 수정에 도움이 될 것이다.

 

32.  데이터 베이스를 소켓, 파일스트림등을 통해 열었을 때는 닫는 로직을 finally에 두어라. 이는 열고난 이후 닫기 전에 오류 발생하여도 마지막에는 닫을 수 있도록 해준다.

 

33.  변수선언은 해당 변수가 최초로 사용되는 곳에 선언하도록 하라. 한 줄에 하나의 변수만 선언하라..

 

34.  루프 문에서 문자열 처리를 해야 할 때는 String 클래스 대신에 StringBuilder 클래스를 사용하라. String 객체는 동작방식이 미묘하여 문자열에 대해 새로운 작업(+, remove 등)이 일어날 때 이전 객체는 파기하고 항상 새로운 객체를 생성하도록 되어있다. 이러한 작업은 비용이 많이 든다.

 

아래의 예를 보자:

 

public string ComposeMessage (string[] lines)

{

   string message = String.Empty;

 

   for (int i = 0; i < lines.Length; i++)

   {

      message += lines [i];

   }

 

   return message;

}

 

위의 예는 단순히 message 변수에 lines 를 이어 붙이는 걸로 보이지만, 실제로 for 문 내에서는 message 객체가 매번 생성되고, 소멸된다.

 

이러한 반복작업을 하게 될 때 String 클래스 대신에 StringBuilder 클래스를 사용하여 비용을 줄이는 것이 현명하다..

 

아래는 String 클래스 대신에 StringBuilder 클래스를 사용하는 예:.

 

public string ComposeMessage (string[] lines)

{

    StringBuilder message = new StringBuilder();

 

    for (int i = 0; i < lines.Length; i++)

    {

       message.Append( lines[i] );

    }

 

    return message.ToString();

}

 

 

 

4.   아카텍처(Architecture)

 

1.   항상 다중 레이어(N-Tier) 아키텍처를 사용하라.

 

2.   UI 페이지에서 DB에 접근하지 말라. 데이터 베이스 접근에 관련된 데이터 엑세스 레이어를 만들어 사용하라. DB변경이 있을 때 도움이 된다.

 

3.   트라이 캐치를 이용해서 DB에서 발생하는 모든 오류를 검출하라. 커맨드명, 프로시저명, 파라메터 등을 기록해두어라. 추후 다른 계층에서 동일한 오류가 발생하면 쉽게 찾을 수 있다.

 

4.   어플리케이션은 여러 개의 어셈블리로 분리하여라.

 

5.   ASP.NET

 

1.   전체 코드에서 세션 값을 사용자 말라. 세션을 사용하는 특정클래스, 메서드를 지정하고 그 메서드에서 만 사용하라. 세션은 System.Web.HttpCOntext.Current.Session 코드를 통해 접근할 수 있다.

 

2.   덩치 큰 데이터를 세션에 저장하지 말라. 세션의 데이터는 유저 수에 따라 늘어나고, 그만큼 많은 웹 서버의 메모리를 차지하게 된다.

 

웹 페이지의 외관을 정의 할 때는 언제나 스타일 시트를 사용하라. 특정 폰트명과 크기를 사용하라. 이는 추후 다른 고객에게 판매하거나 고객에 따른 커스터마이징을 수월하게 해준다.

 

6.   주석

 

의미 있는 좋은 주석은 코드를 유지보수하기 좋게 해주지만,

 

1.   모든 코드, 모든 변수에 주석을 달 필요는 없다.

 

2.   /* ... */ 대신에 // 나 /// 을 사용하라.

 

3.   꼭 필요한 곳에 주석을 작성하라. 읽기 좋은 코드는 주석이 많이 필요하지 않다.

 

4.   주석이 없어도 이해하기 쉬운 코드에는 주석을 작성하지 말라. 매우 많은 주석을 작성했다가 코드가 변경되면 주석을 그에 맞게 수정하지 않는 경우가 있는데, 이는 더욱 혼란스럽게 만든다.

 

5.   잘 쓰여진 코드에 적은 주석은 아름답지만 못 쓰여진 코드에 적은 주석은 흉하다.

 

6.   매우 복잡한 로직을 작성하게 되면 별도의 문서에 충분한 주석, 설명을 작성하라.

 

7.   숫자 값을 특정한 값으로 초기화 하게 되는 경우 문서에 그 값으로 초기화하는 이유를 충분히 작성하여라.

 

8.   결론은 깔끔하고 읽기 좋은 코드는 특별히 다른 주석을 달지 않아도 된다는 것이다.

 

9.   주석의 철자나 문장이 잘못되진 않았는지 확인하라.

 

7.   예외처리

 

1.   아무 처리도 하지 않는 캐치를 작성하지 말라. 이는 추후에 예상한 결과든 예상하지 못한 결과든 모두를 잡아낼 수 없게 된다. 항상 예외가 발생하지 않도록 트라이 블록에서 처리하고, 캐치블록에서는 반드시 예외에 대한 처리를 하라. 최악의 경우 이러한 코딩을 하고 싶다면 로그를 남기고 진행하라.

 

2.   예외발생시 사용자에게는 간결하고 친절한 메시지를 보여주되 내부적으로 시간, 메서드, 인자, 클래스명 등을 로그로 남겨라.

 

3.   일반적인 예외 캐치보다는 좀더 구체적인 예외를 캐치하라.

 

좋은 예:

 

 

         void ReadFromFile ( string fileName )

         {

                  try

                  {

                           // read from file.

                  }

                  catch (FileIOException ex)

                  {

                           // log error.

                           //  re-throw exception depending on your case.

                           throw;

                  }

         }

 

좋지 않은 예:

 

 

void ReadFromFile ( string fileName )

{

   try

   {

      // read from file.

   }

   catch (Exception ex)    

   {

      // Catching general exception is bad... we will never know whether

      // it was a file error or some other error.             

      // Here you are hiding an exception.

      // In this case no one will ever know that an exception happened.

 

      return "";           

   }

}

        

 

4.   모든 메서드에 예외 처리를 할 필요는 없다. 필요한 곳에만 사용하고, 다른 곳에서의 예외발생은 전역 예외처리기를 만들어 해당 예외에 대한 로그를 남기도록 한다.

 

5.   예외를 발생시킬 경우에 기존 명시적인 예외를 발생시키지 말고 thow 문장만을 이용하여 발생시킨다..

 

좋은 예:

 

catch

{

// do whatever you want to handle the exception

 

throw;  

}

 

좋지 않은 예:

 

catch (Exception ex)

{

// do whatever you want to handle the exception

 

throw ex;

}

 

6.   트라이 캐치를 모든 메모에 작성하지 말라. 프로그래밍으로 막을 수 없는 오류가 발생할만한 곳에만 사용하라.

 

7.   긴 코드의 트라이 캐치를 작성하지 말라. 필요하다면 코드의 조각을 구분하고 각각의 조각에 처리를 해주어라. 이는 어떤 오류가 발생했는지 찾기도 쉽고, 사용자에게 메시지를 보여주기에도 수월하다.

 

8.   필요하다면 예외처리를 하는 커스텀 클래스를 작성하라. 만들 때는 SystemException 을 상속받지 말고, ApplicationException 을 상속받도록 하라.