[5장] 형식 맞추기

- 프로그래머라면 형식을 깔끔하게 맞춰 코드를 짜야 한다.

- 코드 형식을 맞추기 위한 간단한 규칙을 정하고, 그 규칙을 착실히 따라야 한다.

- 팀으로 일한다면 팀이 합의해 규칙을 정하고 모두가 그 규칙을 따라야 한다.

- 필요하다면 규칙을 자동으로 적용하는 도구를 활용한다.

형식을 맞추는 목적

- 코드 형식은 중요하다!

- 융통성 없이 맹목적으로 따르면 안 된다... 

- 오늘 구현한 코드의 가독성은 앞으로 바뀔 코드의 품질에 지대한 영향을 미친다.

- 오랜 시간이 지나 원래 코드의 흔적을 더 이상 찾아보기 어려울 정도로 코드가 바뀌어도 맨 처음 잡아놓은 구현 스타일과 가독성 수준은 유지보수 용이성과 확장성에 계속 영향을 미친다.

적절한 행 길이를 유지하라

- 위 이미지는 JUnit, FitNesse, testNG, Time and Money(tam), JDepend, Ant, Tomcat 프로젝트를 조사한 결과.

- 상자를 관통하는 선은 각 프로젝트에서 최대 파일 길이와 최소 파일 길이를 나타낸다.

- 위 이미지를 통해 500줄을 넘지 않고 대부분 200줄 정도인 파일로도 커다란 시스템을 구축할 수 있다는 것.

- 일반적으로 큰 파일보다 작은 파일이 이해하기 쉽다.

신문 기사처럼 작성하라

- 독자는 위에서 아래로 기사를 읽고, 최상단에 기사를 몇 마디로 요약하는 표제가 나온다. 세세한 사실은 숨기고 커다란 그림을 보여준다.

- 소스 파일도 신문 기사와 비슷하게 작성한다.

- 이름은 간단하면서도 설명이 가능하게 지음으로써 이름만 보고도 올바른 모듈을 살펴보고 있는지 아닌지를 판단할 수 있어야 한다.

- 소스 파일 첫 부분은 고차원 개념과 알고리즘을 설명하고, 아래로 내려갈수록 의도를 세세하게 묘사한다. 마지막은 가장 저차원 함수와 세부 내역.

개념은 빈 행으로 분리하라

- 거의 모든 코드는 왼쪽에서 오른쪽으로, 그리고 위에서 아래로 읽힌다.

- 각 행은 수식이나 절을 나타내고, 일련의 행 묶음은 완결된 생각 하나를 표현하고, 생각 사이는 빈 행을 넣어 분리해야 한다.

- 아래 코드는 import문, 각 함수 사이에 빈 행이 들어간다.

- 빈 행은 새로운 개념을 시작한다는 시각적 단서다. 코드를 읽어 내려가다 보면 빈 행 바로 다음 줄에 눈길이 멈춘다.

import *

class BoldWidget(ParentWidget):
	def __init__(self):
    	self.REGEXP = "'''.+?'''"
    	self.pattern = Pattern.compile("'''(.+?)'''", Pattern.MULTILINE + Pattern.DOTALL)
    
    def BoldWidget(self, parent:ParentWidget, text:str):
    	super().__init__()
        self.match = pattern.matcher(text)
        self.match.find()
        self.addChildWidgets(self.match.group(1))
        
    def render(self):
    	self.html = StringBuffer("<b>")
        self.html.append(childHtml()).append("</b>")
        return str(self.html)

- 아래 코드는 위 코드에서 빈 행을 빼버린 코드다. 코드 가독성이 현저하게 떨어져 암호처럼 보인다.

import *
class BoldWidget(ParentWidget):
	def __init__(self):
    	self.REGEXP = "'''.+?'''"
    	self.pattern = Pattern.compile("'''(.+?)'''", Pattern.MULTILINE + Pattern.DOTALL)
    def BoldWidget(self, parent:ParentWidget, text:str):
    	super().__init__()
        self.match = pattern.matcher(text)
        self.match.find()
        self.addChildWidgets(self.match.group(1))
    def render(self):
    	self.html = StringBuffer("<b>")
        self.html.append(childHtml()).append("</b>")
        return str(self.html)

- 눈의 초점을 흐리게 하고 코드를 바라보면 효과는 더욱 분명하게 드러난다...

- 첫 번재 코드는 행 묶음이 분리되어 보이지만, 두 번째 코드는 전체가 한 덩어리로 보인다.

세로 밀집도

- 줄바꿈이 개념을 분리한다면, 세로 밀집도는 연관성을 의미한다. 서로 밀집한 코드 행은 세로로 가까이 놓여야 한다.

- 의미 없는 주석으로 두 인스턴스 변수를 떨어뜨려 놓았다.

class ReporterConfig():
	def __init__(self):
    	### 
        # 리포터 리스너의 클래스 이름
        ###
    	self.m_className = ""
              
        ###
        # 리포터 리스너의 속성
        ###
        self.m_propertiees = []
        
    def addProperty(self, property):
        self.m_properties.add(property)

- 아래 코드가 훨씬 더 읽기 쉽다. 코드가 한 눈에 들어온다.

class ReporterConfig():
	def __init__(self):
    	self.m_className = ""
        self.m_propertiees = []
        
    def addProperty(self, property):
        self.m_properties.add(property)

수직 거리

- 서로 밀접한 개념은 세로로 가까이 둬야 한다. (물론 두 개념이 서로 다른 파일에 속한다면 규칙 통하지 않음)

- 타당한 근거가 없다면 서로 밀접한 개념은 한 파일에 속해야 마땅하다. 이것이 바로 protected 변수를 피해야 하는 이유 중 하나

- 같은 파일에 속할 정도로 밀접한 두 개념은 세로 거리로 연관성을 표현한다.

- 연관성 : 한 개념을 이해하는 데 다른 개념이 중요한 정도.

 

변수 선언

- 변수는 사용하는 위치에 최대한 가까이 선언한다.

- 우리가 만든 함수는 매우 짧으므로 지역 변수는 각 함수 맨 처음에 선언한다.

def readPreferences():
	is = NULL
    try:
    	is = FileInputStream(getPreferencesFile())
        setPreferences(Properties(getPreferences())
        getPreferences().load(is)
    except IOException e:
    	try:
        	if is != NULL:
            	is.close()
        except IOException e1:
        	pass

- 루프를 제어하는 변수는 루프 문 내부에 선언한다.

def countTestCases():
	count = 0
    for each in tests:
    	count += each.countTestCases()
    return count

- 아주 드물지만 다소 긴 함수에서 블록 상단이나 루프 직전에 변수를 선언하는 사례도 있다.

for test in m_suite.getTests():
	tr = m_runnerFactory.newTestRunner(self, test)
    tr.addListener(m_testReporter)
    m_testRunners.add(tr)
    
    invoker = tr.getInvoker()
    
    for m in tr.getBeforeSuiteMethods():
    	beforeSuiteMethodds.put(m.getMethod(), m)
        
    for m in tr.getAfterSuiteMethods():
    	afterSuiteMethods.put(m.getMethod(), m)

 

인스턴스 변수

- 인스턴스 변수는 클래스 맨 처음에 선언한다.

- 잘 설계한 클래스는 클래스의 많은(혹은 대다수) 메서드가 인스턴스 변수를 사용하기 때문에 변수 간에 세로로 거리를 두지 않는다.

- C++에서는 모든 인스턴스 변수를 클래스 마지막에 선언한다는 소위 가위 규칙(scissors rule)을 적용.

- Java엥서는 보통 클래스 맨 처음에 인스턴스 변수를 선언한다.

- 사실 큰 상관은 없지만,,, 잘 알려진 위치에 인스턴스 변수를 모은다는 사실이 중요!

class TestSuite(Test):
	def createTest(self, theClass, name):
    	pass
        
    def getTestConstructor(self, theClass):
    	pass
        
    def warning(self, message):
    	pass
        
    def exceptionToString(self, t):
    	pass
        
    def __init__(self):
    	self.fName = ""
        self.fTests = []
        
    def TestSuite(self):
    	pass
        
    def TestSuite(self, theClass):
    	pass
        
    def TestSuite(self, theClass, name):
    	pass

 

종속 함수

- 한 함수가 다른 함수를 호출한다면 두 함수는 세로로 가까이 배치한다.

- 호출하는 함수를 호출되는 함수보다 먼저 배치함으로써 프로그램이 자연스럽게 읽힐 수 있도록 한다.

- 규칙을 일관적으로 적용한다면 독자는 방금 호출한 함수가 잠시 후에 정의되리라는 사실을 예측한다.

class WikiPageResponder(SecureResponder):
	def __init__(self):
    	page = ""
        pageData = ""
        pageTitle = ""
        request = ""
        crawler = ""
        
    def makeResponse(self, context, request):
		self.pageName = self.getPageNameOrDefault(request, "FrontPage")
        self.loadPage(self.pageName, context)
        if self.page == NULL:
        	return notFoundResponse(context, request)
        else:
        	return makePageResponse(context)
            
	def getPageNameOrDefault(self, request, defaultPageName):
    	self.pageName = request.getResouce()
        if StringUtil.isBlank(self.pageName):
        	self.pageName = defaultPageName
        
        return pageName

	def loadPage(self, resource, context):
    	self.path = PathParser.parse(resource)
        self.crawler = context.root.getPageCrawler()
        self.crawler.setDeadEndStrategy(VirtualEnabledPageCrawler())
        self.page = self.crawler.getPage(context.root, path)
        if self.page != NULL:
        	self.pageData = self.page.getData()
            
	def notFoundResponse(self, context, request):
    	return NotFoundResponder().makeResponse(context, request)
        
	def makePageResponse(self, context):
    	self.pageTitle = PathParser.render(self.crawler.getFullPath(page))
        self.html = makeHtml(context)
        
        self.response = SimpleResponse()
        self.response.setMaxAge(0)
        self.response.setContent(html)
        return response

 

 

개념적 유사성

- 어떤 코드는 개념적인 친화도가 높기 때문에 서로 끌어당긴다. 친화도가 높을수록 코드를 가까이 배치한다.

- 한 함수가 다른 함수를 호출해 생기는 직접적인 종속성, 그리고 변수와 그 변수를 사용하는 함수일 때 친화도가 높다.

class Assert():
	def assertTrue(self, message, condition):
    	if not condition:
        	fail(message)
            
	def assertTrue(self, condition):
    	assertTrue(NULL, condition)
        
	def assertFalse(self, message, condition):
    	assertTrue(message, !condition)
        
	def assertFalse(self, condition):
    	assertFalse(NULL, condition)

- 위 함수들은 명명법이 똑같고 기본 기능이 유사하고 간단한, 개념적인 친화도가 높은 함수들이다.

- 서로가 서로를 호출하는 관계는 부차적인 요인이다. 종속적인 관계가 없더라고 가까이 배치할 함수들이다.

세로 순서

- 일반적으로 함수 호출 종속성은 아래 방향으로 유지된다. 호출되는 함수를 호출하는 함수보다 나중에 배치함으로써 소스 코드 모듈이 고차원에서 저차원으로 자연스럽게 내려가도록 한다.

- 가장 중요한 개념을 가장 먼저 표현하고, 세세한 사항을 최대한 배제하고 이 내용은 가장 마지막에 표현한다.

가로 형식 맞추기

 

- 위 그림을 통해 프로그래머는 명백하게 짧은 행을 선호함을 확인할 수 있다.

가로 공백과 밀집도

- 가로로는 공백을 사용해 밀접한 개념과 느슨한 개념을 표현한다.

def measureLine(line):
	lineCount += 1
    lineSize = len(line)
    totalChars += lineSize
    lineWidthHistogram.addLine(lineSize, lineCount)
    recordWidestLine(lineSize)

- 할당 연산자를 강조하려고 앞뒤에 공백을 줬다. 할당문은 왼쪽 요소와 오른쪽 요소가 분명히 나뉜다. 공백을 넣으면 두 가지 주요 요소가 확실히 나뉜다는 사실이 분명해진다.

- 함수 이름과 이어지는 괄호 사이에는 공백을 넣지 않았다. 함수와 인수는 서로 밀접하기 때문이다.

- 공백을 넣으면 한 개념이 아니라 별개로 보인다.

- 함수를 호출하는 코드에서 괄호 안 인수는 공백으로 분리했다. 쉼표를 강조해 인수가 별개라는 사실을 보여주기 위해서.

- 연산자 우선순위를 강조하기 위해서도 공백을 사용한다.

import math

class Quadratic():
	def root1(self, a, b, c):
    	self.determinant = self.determinant(a, b, c)
        return (-b + math.sqrt(self.determinant)) / (2*a)
	
    def root2(self, a, b, c):
    	self.determinant = self.determinant(a, b, c)
        return (-b - math.sqrt(self.determinant)) / (2*a)
        
	def determinant(self, a, b, c):
    	return b*b - 4*a*c

- 곱셈은 우선순위가 가장 높기 때문에 승수 사이는 공백이 없다.

- 덧셈과 뺄셈은 우선순위가 곱셈보다 낮기 때문에 항 사이에는 공백이 들어간다.

가로 정렬

class FitNesseExpediter(ResponseSender):
	def __init__(self):
        self.socket		=	""
        self.input		=	""
        self.output 		= 	""
        self.request		=	""
        self.response	=	""
        self.context		= 	""
        self.requestParsingTimeLimit	=	""
        self.requestProgress	=	""
        self.requestParsingDeadline	=	""
        self.hasError	=	""
        
    def FitNesseExpediter(self, s, context):
    	self.context	=	context
        self.socket		=	s
        self.input		=	s.getInputStream()
        self.output		=	s.getOutputStream()
        self.requestParsingTimeLimit	=	10000

 

- 위 코드는 정렬을 함으로써 코드가 엉뚱한 부분을 강조해 진짜 의도를 가리고 있다.

- 정렬하지 않으면 오히려 중대한 결함을 찾기 쉽다.

- 정렬이 필요할 정도로 목록이 길다면 문제는 목록 길이지, 정렬 부족이 아니다.

class FitNesseExpediter(ResponseSender):
	def __init__(self):
        self.socket	= ""
        self.input	= ""
        self.output = ""
        self.request = ""
        self.response =	""
        self.context = ""
        self.requestParsingTimeLimit = ""
        self.requestProgress = ""
        self.requestParsingDeadline = ""
        self.hasError = ""
        
    def FitNesseExpediter(self, s, context):
    	self.context = context
        self.socket	= s
        self.input = s.getInputStream()
        self.output = s.getOutputStream()
        self.requestParsingTimeLimit = 10000

들여쓰기

- 소스 파일은 윤곽도와 계층이 비슷하다.

- 파일 전체에 적용되는 정보가 있고, 파일 내 개별 클래스에 적용되는 정보가 있고, 클래스 내 각 메서드에 적용되는 정보가 있고, 블록 내 블록에 재귀적으로 적용되는 정보가 있다.

- 계층에서 각 수준은 이름을 선언하는 범위이자 선언문과 실행문을 해석하는 범위.

- 범위(scope)로 이뤄진 계층을 표현하기 위해 우리는 코드를 들여쓴다... 들여쓰는 정도는 계층에서 코드가 자리잡은 수준에 비례

- 왼쪽으로 코드를 맞춰 코드가 속하는 범위를 시각적으로 표현함으로써 이 범위에서 저 범위로 재빨리 이동하기 쉬워진다.

# 1
class FitnesseServer(SocketServer): def __init__(self): self.context = ""
def FitNesseServer(self, context): self.context = context def server(self, s):
self.serve(s, 10000) def server(self, s, requestTimeout): try : self.sender = 
FitNesseExpediter(s, context) self.sender.setRequestParsingTimeLimit(requestTimeout)
sender.start() except Exception e: e.printStackTrace()

# 2
class FitnesseServer(SocketServer):
	def __init__(self):
    	self.context = ""
        
	def FitNesseServer(self, context):
    	self.context = context
        
    def server(self, s):
		self.serve(s, 10000)
        
    def server(self, s, requestTimeout):
    	try :
        	self.sender = FitNesseExpediter(s, context)
            self.sender.setRequestParsingTimeLimit(requestTimeout)
            sender.start() 
        except Exception e:
        	e.printStackTrace()

- 들여쓰기한 파일은 구조가 한눈에 들어온다. 변수, 생성자 함수, 접근자 함수, 메서드가 금방 보인다.

- 들여쓰기 하지 않은 코드는 열심히 분석하지 않는 한 거의 불가해하다.

 

들여쓰기 무시하기

- 때로는 간단한 if문, 짧은 while문, 짧은 함수에서 들여쓰기 규칙을 무시하고픈 유혹이 생기지만... 들여쓰기 필수!

# 1
class CommentWidget(TextWidget):
	def __init__(self):
    	self.REGEXP = "^#[^\r\n]*(?:(?:\r\n)|\n|\r)?"

	def CommentWidget(self, parent, text): super.__init__(parent, text)
    def render(self): return ""
    
# 2
class CommentWidget(TextWidget):
	def __init__(self):
    	self.REGEXP = "^#[^\r\n]*(?:(?:\r\n)|\n|\r)?"

	def CommentWidget(self, parent, text):
    	super.__init__(parent, text)
        
    def render(self):
    	return ""

가짜 범위

- 때로는 빈 while문이나 for문을 접한다. 이 구조를 피하지 못할 떄는 빈 블록을 올바르게 들여쓰고 괄호로 감싼다.

- 세미콜론(;)은 새 행에다 제대로 들여써서 넣어준다. 그렇게 하지 않으면 눈에 띄지 않는다.

while (dis.read(buf, 0, readBufferSize) != -1):
	pass

팀 규칙

- 프로그래머라면 각자 선호하는 규칙이 있다. 하지만 팀에 속한다면 자신이 선호해야 할 규칙은 바로 팀 규칙이다.

- 팀은 한 가지 규칙에 합의해야 하고, 모든 팀원이 그 규칙을 따라야지만 소프트웨어가 일관적인 스타일을 보인다.

- 좋은 소프트웨어 시스템은 읽기 쉬운 문서로 이루어진다.

- 스타일은 일관적이고 매끄러워야 하며, 한 소스 파일에서 봤던 형식이 다른 소스 파일에도 쓰이리라는 신뢰감을 독자에게 줘야 한다.

밥 아저씨의 형식 규칙

- 코드 자체가 최고의 구현 표준 문서가 되는 예.

class CodeAnalyzer(JavaFileAnalysis):
	def __init__(self):
    	self.lineCount = 0
        self.maxlineWidth = 0
        self.widestLineNumber = 0
        self.lineWidthHistogram = ""
        self.totalChars = 0
        
    def CodeAnalyzer(self):
    	self.lineWidthHistogram = LineWidthHistogram()
        
	def findJavaFiles(self, parentDirectory, files):
    	for file in parentDirectory.listFiles():
        	if file.getName().endsWith(".java"):
            	files.add(file)
            elif file.isDirectory():
            	self.findJavaFiles(file, files)
                
	def analyzeFile(self, javaFile):
    	self.br = BufferedReader(FileReader(javaFile))
        self.line = ""
        while (self.line = br.readLine()) != NULL:
        	self.measureLine(self.line)
            
	def measureLine(self, line):
    	self.lineCount += 1
        self.lineSize = len(line)
        self.totalChars += self.lineSize
        self.lineWidthHistogram.addLine(self.linesize, self.lineCount)
        self.recordWidestLine(self.linesize)
        
	def recordWidestLine(self, lineSize):
    	if (lineSize > self.maxLineWidth):
        	self.maxLineWidth = lineSize
            self.widestLineNumber = self.lineCount
            
	def getLineCount(self):
    	return self.lineCount
        
	def getMaxLineWidth(self):
    	return self.maxLineWidth
        
	def getWidestLineNumber(self):
    	return self.widestLineNumber
        
	def getLineWidthHistogram(self):
    	return self.lineWidthHistogram
        
	def getMeanLineWidth(self):
    	return float(self.totalChars/self.lineCount)
        
	def getMedianLineWidth(self):
    	self.sortedWidths = self.getSortedWidths()
        self.cumulativeLineCount = 0
        for width in sortedWidths:
        	self.cumulativeLinecount += self.lineCountForWidth(self.width)
            if self.cumulativeLineCount > self.lineCount/2:
            	return width

	def lineCountForWidth(self, width):
    	return self.lineWidthHistogram.getLinesforWidth(width).size()
        
	def getSortedWidths(self):
    	self.widths = self.lineWidthHistogram.getWidths()
        self.sortedWidths = self.widths.toArray([0])
		self.sortedWidths.sort()
        return self.sortedWidths