"자기 문서화"는 어떻게 성가 시게하지 않고 코드가 될 수 있습니까? [닫은

https://stackoverflow.com/questions/214160

03-07-2019
|

문제

모범 사례가 무엇인지 잘 모르겠지만, 특히 범위가 작을 때 약식 변수 이름을 자주 볼 수 있습니다. 그래서 (간단한 루비 예제를 사용하려면) 대신 def add_location(name, coordinates), 나는 같은 것을 본다 def add_loc(name, coord)- 그리고 나는 심지어 같은 것을 볼 수도 있습니다 def add_loc(n, x, y). 나는 더 긴 이름이 약어를 보는 것에 익숙 할 때 사람을 피곤할 수 있다고 생각합니다.

Verbosity는 가독성에 도움이됩니까, 아니면 모든 사람의 눈을 아프게합니까? - 사람들은 더 긴 이름보다 약어와 이름이 단축 된 이름을 선호합니까?

해결책

개인적으로, 나는 컨텍스트를 먼저 결정하지 않고 실제로 무언가를 의미하는 더 긴 이름을 많이 보게 될 것입니다. 물론, 카운터와 같이 실제 의미를 부여하지 않는 변수는 여전히 작은 의미없는 변수 이름 (예 : i 또는 x), 그러나 그렇지 않으면 진실성은 명확합니다 대부분의 시간. 이것은 특히 공개 API에 해당됩니다.

그러나 이것은 너무 멀리 취할 수 있습니다. 나는 과거에 그런 식으로 어리석은 VB 코드를 보았습니다. 다른 모든 것과 같은 중재!

다른 팁

나는 실제로 모든 현대 IDE와 TextedITORS가 완료된 후에 항상 긴 변수 이름을 항상 사용하므로 사용에 아무런 문제가 없습니다. index 대신 내가. 내가 가진 유일한 예외는 좌표를 다룰 때 B/C입니다. x 그리고 y 거기에서 가장 이해하십시오.

절대로 ABBR.

변수는 그 목적을 적절하게 전달할 수있는 가장 짧은 이름을 부여해야합니다.

과도한 비료는 구문을 은폐하는 경향이 있으며 구문은 중요합니다.

전체 프로그램 (또는 응용 프로그램/시스템) 변수에 걸쳐 일관된 스타일로 이름을 지정해야하며 유사한 것을 비슷하게 지정해야합니다. 언어 커뮤니티 내에 협약이 존재하는 경우, 그렇게하지 않을 강력한 이유가 없다면 관찰되어야합니다 (따라서 Camelcaserubyvariablenames를 사용하지 마십시오).

사용하는 경우 약어는 어디서나 지속적으로 적용되어야하며 도메인 별 경우 어딘가에 기록되어야합니다. 누군가가 코드로 유용한 시간을 보내려면 곧 배울 것입니다.

변수의 이름을 지정하기 위해 최대 5 ~ 6 개의 단어를 결합 해야하는 경우 코드 냄새 그리고 당신이 일하는 일상은 약간의 작업에서 혜택을 볼 수 있습니다.

하지만 대부분은 함정을 알고 있다면 실제로 생각한다 당신이 쓰고있는 것에 대해, 당신의 코드가 합리적 일 것입니다. 새로운 동료에게 작업중 인 기능을 설명한다고 상상해보십시오.

1 년 후에 자신의 코드를 읽으십시오. 자체 문서화 변수 이름의 값과 코드 댓글의 값 (특히 클린 코드의 값)이 모두 표시됩니다.

다른 사람 소스 코드를 잡고 이해하지 못하면 "잘 나만 올라가는 프로그래머가 아니라고 생각하기 쉽다"고 생각하기 쉽지만 자신의 코드가 읽기가 어렵다는 것을 깨달았을 때 : "내가 뭐였 니 생각? "

장기적으로는 진실성이 유지 가능성에 도움이됩니다. 짧은 One Line 스크립트의 경우 SetLocationName 대신 "setlocnm"을 사용할 수 있습니다. "

모든 바보는 컴퓨터가 이해할 수있는 코드를 쓸 수 있습니다. 좋은 프로그래머는 인간이 이해할 수있는 코드를 작성합니다. -Martin Fowler

개인적으로, 나는 진실성이 좋은 것을 발견하지만 지나치게 장황한 것은 쉽습니다. 이것은 나쁜 것입니다. 균형이 있으며, 약어도 그 균형에 들어올 수 있습니다.

이것들은 나의 일반적인 규칙입니다.

반복자는 한 글자가 될 수 있습니다. i, j, k, 등.
부울 토글과 같은 다른 하나의 단어 변수, 당신은 결코 약자가되지 않은 것, 즉. installing, done, 등.
다중 단어 변수와 기능 이름은 약어 후보이지만, 단정하게 길어지기 시작한 경우에만 (예 : 20-25+ 문자). 지능적인 약어가 여기서 핵심입니다. function => func 예를 들어, 결코 fun, f, 또는 functi

답을 찾아 냈지만 다음이 다루어 졌는지 알 수 없습니다. 여기 간다...

당신이 약칭이든 장황하든, 필요한 것보다 더 이상 단어를 사용하지 않았으며 의미가 명백하다는 것을 확인하십시오.

그러나이 필터링 후에도 식별자가 장황 해 보이면 디자인에 결함이 있습니다.

def initialize_report_template()
end

... 했어야 했어 ...

class ReportTemplate
    def initialize()
    end
end

더 긴 이름이 훨씬 좋습니다. 당신은 종종 작은 스코프로 약식 이름을 본다고 언급합니다. 소프트웨어가 성장함에 따라 범위가 작을 것이라고 누가 말할 수 있습니까?

물론, xcoordinateforcurrentlocationofofoves는 말도 안되는 이름이므로 합리적입니다. 특히 이전에 작업하지 않은 프로젝트에 들어가면 설명 기능과 가변 이름을 사용한 사람에게 감사드립니다.

이름이 가독성을 상하게하거나 중복 될 때 약어를해도 괜찮다고 생각합니다.

예 1 : 유형이 모든 정보를 전달하는 방법에 대한 인수.

예 2 : 명백한 방식으로 많이 사용할 변수

StringBuilder sb = ...
sb.append(...
sb.append(...
return sb.toString();

예 3 : 관용 약어. I, J, K가 모두 언급되었습니다. 위의 "SB"는 코드 중 하나이며 각 팀에는 몇 가지가 더있을 것입니다.

더 길지 않고 짧은 것을 목표로하지만 독자의 이해는 트럼프해야합니다. 입력하기위한 게으름 매번.

다른 사람들이 말했듯이, 가변 이름 길이는 논리 나 알고리즘을 모호하게해서는 안됩니다. 예를 들어, 산술에서 우리는 씁니다

( 1 + 5 ) * 3 = 18

보다는

three multiplied by the sum of one and five equals eighteen

우리는 표현에 관련된 요소의 명확성 이외의 다른 것들에주의를 기울이려고 노력하고 있기 때문입니다.

나는 변수를 1 ~ 3 단어로 유지하는 경향이 있으며, 24 자 정도를 초과 할 때만 약어를 줄입니다. 변수가 덜 사용될수록 변수 이름을 길게 만들 수있을 가능성이 높아집니다. 더 자주 사용되는 변수는 더 짧게 만들 것입니다.

Bugzilla의 최고 건축가 인 Max Kanat-Alexander는이를 블로그에서 말합니다.

코드 자체는 의미의 양에 비례하여 공간을 차지해야합니다.

기본적으로, 많은 것을 의미하는 작은 기호는 코드를 읽기 어렵게 만듭니다. 많이 의미하지 않는 매우 긴 이름은 코드를 읽기 어렵게 만듭니다. 의미의 양과 공간은 서로 밀접하게 관련되어야합니다.

http://www.codesimplicity.com/post/readability-and-naming-things/

이름 지정에 대한 매우 통찰력있는 게시물입니다. 나는 모두가 그것을 읽을 것을 촉구합니다!

내가 약어를 받아들이는 유일한 시간은 작은 기간 동안 범위에있는 로컬 변수에 대한 것입니다.

의미가 매우 읽기 쉬운 방법이나 생성자로 범위로 들어와야한다는 의미입니다.

나는 Kilhoffer에 동의합니다. 거의 모든 맥락에서 설명 변수 이름을보고 싶어합니다. 내 변수 이름이 20 자 미만인 경우 약칭을 할 것입니다. 일반적으로 변수 이름의 단어가 있습니다 (예 : "someverylongvarvalue").

물론, 나는 또한 가능할 때마다 헝가리 표기법을 사용하기 때문에 당신의 관점에 따라 내 변수의 이름을 지나치게 설명 적으로 만들려고 노력하는 다른 극단 캠프에있을 수 있습니다.

나는 아마도 완전히 구멍을 뚫을 것입니다. 그러나 나는이 견해가 들렸다는 것을 확인하고 싶었습니다.

더 긴 변수 이름은 더 설명적일 수 있지만 프로그램의 원래 의도를 시작할 수 있습니다. API 요소에서는 사용될 상황에서 명확하고 의미있는 이름을 갖는 것이 중요하다고 생각합니다.

각 함수 또는 방법 내에서 이것은 종종 다른 이야기입니다. 나는 덜 쓰고 그것을 매우 간결하게 유지하려고 노력합니다. 이것은 스파르타 프로그래밍 Al a로 알려져 있습니다 Atwood 씨 그리고 이것 멋진 예. 그렇습니다. 그 예는 명확하게 조작되었지만 약간 덜 의식을 갖는 것이 실제로 프로그램을 더 쉽게 읽을 수있는 방법을 보여줍니다.

행운을 빕니다.

프로그래밍 할 때는 인간이 읽을 수 있도록 구문을 사용하는 것입니다. 변수 이름, 메소드 등의 길이는 실제로는 무의미합니다.

장애가 더 좋을수록 일반적으로 좋은 개발 환경을 사용하면 코드가 완료되어야하므로 "add_l"+탭을 누르면 메소드 호출을 완료 할 수 있습니다.

약어의 주요 문제는 모든 사람들이 같은 방식으로 할인되는 것은 아닙니다, 많은 사람들과 함께 일할 때 코딩시 오류 확률 만 증가 할 수 있습니다. 예를 들어 Something_interface라고 할 수있는 상수가있는 경우 일부 개발자는 무언가를 Something_intface로, 다른 개발자는 Something_iface 또는 Something_if, smthing_iface로 약칭 할 수 있습니다.

두 단어 만 있으면 적어도 6 개 이상의 "논리"가능한 약어를 가질 수 있으므로, 대부분의 경우 약어없이 글을 쓰는 것이 더 낫다고 생각합니다. .

매우 긴 이름은 때때로 성가시킬 수 있지만 보조 변수를 사용하여 매우 로컬 스코프에서 약칭 할 수도 있습니다.

대부분의 사람들은 읽은 시야를 읽고, 더 이상 단어를 읽은 다음 개별 편지를 읽는 데 걸리지 않습니다. 따라서 항상 의미있는 이름을 사용하십시오. 그들은 7 개의 단어 설명을 완료해야합니까? 그러나 이해하기에 충분히 길어야합니다.

Add_loc (이름, 코드)을 받아 들일 수 있습니다. add_loc (n, x, y)에서는 이름 대신 'n'에 반대합니다. 나는 X와 Y와 함께 살 수 있었다.

좌표 시스템에 익숙하지 않은 사람의 경우 add_location (이름, 좌표)이 더 의미가있는 위치를 알 수 있습니다.

의심스러운 경우 더 긴 이름을 사용하십시오.

"살인 미스터리를 알아내는 것은 괜찮지 만 코드를 알아낼 필요는 없습니다. 읽을 수 있어야합니다." -Steve C. McConnell

즉, 당신과 다른 사람이 지나치게 명백한 변수 이름이 필요하다고 생각한다면 자유롭게 단축하십시오.

미니멀리스트 접근 방식을 취하는 것이 좋습니다. 코드가 명확하고 간결하며 시점에 유지되도록 가능한 한 조금 사용하십시오.

상수 및 글로벌과 같은 범위를 벗어난 것은 서술적인 이름이 길어야합니다. 때로는 정말 긴 이름으로 인해 원치 않는 것으로 존재한다는 신호를 보내기에 충분히 "냄새"가됩니다. 이것은 1- 사람들이 그것을 피하게 만들기 때문에 좋은 것입니다. 2- 코드를 리팩터링하여 코드를 제거하기 위해 언론을 늘리십시오.

라이센스 : CC-BY-SA ~와 함께 속성

제휴하지 않습니다 StackOverflow