다음 개발자가 코드를 더 쉽게 이해할 수 있도록하려면 어떻게해야합니까?

다음 개발자가 코드를 더 쉽게 이해할 수 있도록하려면 어떻게해야합니까?

---

저는 지금까지 약 8 개월 동안 처음으로 프로그래밍 작업을했고 지금까지 엄청난 양을 배웠습니다.

불행히도 저는 내부 애플리케이션을위한 소규모 스타트 업 회사의 유일한 개발자입니다.

하지만 처음으로이 직장을 떠날 때 내 프로젝트 중 일부를 다른 사람에게 넘겨 줄 것입니다. 나는 내 모든 프로젝트를 철저히 문서화했지만 (적어도 그렇게 생각한다), 다른 누군가가 내 코드를 읽는 것에 대해 여전히 긴장된다.

예를 들어, 저는 항상 이런 일을 해왔습니다.

for (int i = 0; i < blah.length; i++)
{
//Do stuff
}

설명적인 이름을 'i'로 지정해야합니까? 임시 변수 일 뿐이며 해당 루프 내에 만 존재하며 루프가 'i'로 무엇을하는지 매우 명백한 것 같습니다.

이것은 하나의 예일뿐입니다. 또 다른 하나는 변수 이름을 다르게 지정한다는 것입니다. 모든 개인 멤버를 밑줄로 시작하는 것 외에는 이름 지정 표준을 실제로 따르지 않습니다.

다음 개발자를 위해 더 쉽게 만드는 방법을 보여줄 수있는 리소스가 있습니까? 이런 종류의 것에 대한 표준이 있습니까?

---

Steve McConnell의 Code Complete 는 귀하의 질문에 대한 답변을 찾기 시작하기에 좋은 곳이며, 아직 묻지 않았지만 곧있을 것입니다.

---

다음을 완료하면 교체의 고통을 덜어주는 데 큰 도움이됩니다.

1. 소프트웨어의 전체 구조와 상호 작용하는 부분을 보여주는 아키텍처 문서를 생성합니다.
2. 모든 멤버 변수 / 함수 / 클래스를 문서화하여 그들이하는 일을 표시하십시오 (그들이하는 방법이 아님).
3. 프로그램의 작동 방식과 예상되는 방식을 보여주는 테스트를 작성하고 문서화하십시오. 확인 어떤 예를 들어 데이터가 있으므로 교체 할 수있는 기록이 방법의 이해를 얻기 위해 테스트를 다시 실행 해야 작동합니다.
4. 코드가 표준을 따르는 지 확인하십시오. 기존 코드가 아니더라도 최소한 자체적으로 일관성이있는 코드는 따라 가기가 더 쉬울 것입니다.
5. 당신이 그것에 익숙하다면, 인수하는 남자 또는 여자가 정말로 막혀있을 때 적어도 이메일을 보내거나 전화를 줄 수 있도록 연락처 정보를 남겨주세요. 저는 다양한 프로젝트 / 직업을 위해 이것을했습니다. 이상한 질문에 대답하는 데 오래 걸리지 않지만 코드베이스를 많은 시간에 물려받은 쏟아지는 영혼을 쉽게 구할 수 있습니다.

코딩 표준을 준수하려면 여기에 몇 가지 제안 사항이 있는 관련 게시물이 있습니다 .

---

"실제 작업"의 요점 외에도 (-이전 3 개의 답변은 꽤 좋습니다-) 우리 (프로그래머)는 오만하고 (거의 무지한) 괴상한 무리라는 것을 명심하십시오.

아무리 좋은 (그리고 잘 문서화 된) 코드를 작성하려고 노력하거나 얼마나 많은 구문을 적용 할 것인지에 관계없이 새 사람에게는 그가 작성 하지 않았기 때문에 코드가 항상 (적어도 어느 정도까지는) "흡수"됩니다. 그것.

귀하의 예 (i for 루프 사용)의 경우 로컬 루프 변수 일뿐입니다. 나는 너 자신에게 너무 힘들지 않을 것이다. 코드가 자명 한 한 그는 관리 만하면됩니다.

---

변수 중 i특별한 이름 지정 사례로 간주됩니다. 과 함께 j, k그리고 l, i루프에서 사용하기위한 임시 "카운터"변수로 잘 이해된다. 사용이 일관된 한 문제가되지 않습니다.

다음은 코드를 더 쉽게 이해하기 위해 따라야 할 몇 가지 좋은 규칙입니다.

• 일관성 유지 : 변수 이름 지정 규칙과 디자인이 일관성이 있는지 확인합니다. 루프에 대한 임시 변수를 자주 생성하는 경우 항상 호출 i됩니까? i다른 것을 의미하기 위해 다른 곳에서 사용 합니까? 일관성은 코드에 논리 패턴이 있음을 의미합니다. 패턴은 선택하고 따라 가기 쉽습니다.
• 자신을 설명하세요 : 댓글에 자신 이하는 일이 아니라 왜 무언가를하고 있는지 설명해야합니다 . 같은 댓글은 // Loop over array도움이되지 않습니다. 누구나 코드를 읽고 루프를 수행하는 것을 볼 수 있습니다. 그들이 알고 싶어하는 것은 당신이 그것을하는 이유입니다.
• 클래스 문서화 : 모든 클래스, 인터페이스, 멤버, 속성의 목적에 대한 문서를 누군가에게 제공하는 것은 응용 프로그램의 구성 요소가 무엇을하는지 이해하려고 할 때 큰 도움이됩니다. Visual Studio에서 XML 주석을 켜면 각 구성원에 대한 최소한의 요약을 추가하는 것을 잊을 때마다 경고가 생성됩니다. 이 주석은 또한 인텔리 센스 지원의 추가 보너스를 포함하여 코드 작업을 더욱 쉽게 만듭니다.

귀하의 코드가 이러한 지침을 따른다고 말할 수 있다면 귀하의 코드를 상속 받게되어 기쁩니다. 솔직히 말해서, 이러한 조언 중 하나 라도 따르는 코드베이스를 아직받지 못했지만 , thenextguy의 일을 훨씬 쉽게 만들기 위해 내 자신의 코드를 작성합니다.

---

내가 아는 두 가지 도구가 많이 도움이 될 수 있습니다. StyleCop 및 FxCop . 링크를 따라 가면 이러한 도구가 무엇인지 알 수 있습니다. 이러한 도구를 사용하는 것의 가장 큰 장점은 의심 할 여지없이 매우 오랜 시간이 걸리는 코드를 수동으로 검토 할 필요가 없다는 것입니다.

---

경험을 통해 말할 수 있습니다. 다른 사람들은 아름다운 코드를 작성하지 않습니다 . 실제로 코드가 문서화되어 있다면 이미 평균보다 훨씬 낫습니다.

긴장하지 마십시오. 똑같이 쓰는 방법은 수백 가지가 있습니다. 모든 개발자는 자신의 방식이 최고라고 생각합니다. IMHO, 코딩 스타일에서 중요한 것은 일관성입니다. 따라서 "항상 이런 종류의 작업을 수행"했다면 일관된 코드를 갖게됩니다.

---

이 특정 구조는 일반적이며 여기서 'i'는 괜찮습니다.

다른 예는 주관적이며 관례에 일관성이있는 한 괜찮습니다.

주로 : 일관성 유지

편집 : 참고로 다음과 같이 사용할 수 있습니다.

코드 이름 규칙 참조

---

이는 분명해야하지만 모든 단일 프로덕션 구성 요소에 소스 코드가 즉시 사용 가능하고 컴파일 가능한 상태인지 확인해야합니다. 새로운 사람이 새 컴퓨터를받을 가능성이 있으므로 앱을 컴파일하는 데 필요한 컴퓨터 특정 설정이 없는지 확인하십시오.

곧 떠날 예정이라면 "표준"을 준수하기 위해 코드를 리팩토링하지 않는 것이 좋습니다. 좋은 스타일은 중요하지만 새로운 사람이 고쳐야 할 새로운 버그를 너무 많이 도입해서는 안됩니다.

그리고 당신의 앱은 소스 제어에 있습니다 ... 그렇죠?

---

모든 사람은 다른 사람의 코드가 엉망이라고 생각합니다. 그리고 당신은 당신의 코드도 짜증 난다고 생각해야합니다. 왜? 그렇기 때문에. 정말 그렇습니다.

다른 사람의 프로젝트를 유지하고 코드를 검토해야 할 때 그 사람과 직업, 담당자에 대해 네 글자로 중얼 거린다는 것을 알고 있습니다 ... 결국 이해의 지점에 도달하고 그 사람이 문제와 코딩 스타일에 대해 어떻게 생각했는지 파악하십시오.

다른 사람들의 코딩 스타일에 적응하는 것은 쉽지 않습니다. 그래서 팀은 코딩 표준과 코드 리뷰를 가지고 있습니다. 이러한 것들은 적어도 대부분의 경우 고통을 덜어줍니다.

코드와 프로젝트를 문서화하고 (즉,이 일이 무엇을 하는가?) 프로그램이 프로덕션 (실제로 사용 중입니다!)에 있다면 다음 사람은 코드를 제외하고는 불평 할 것이 많지 않아야합니다. :)

---

다음은 도움이 될만한 좋은 기사입니다.

http://msdn.microsoft.com/en-us/library/xzf533w0(v=VS.71).aspx

당신은 또한 새로운 사람이 당신의 모든 언어를 만들기 전에 당신의 " Refactor "명령 에 대해 약간의 시간을 할애 할 수 있습니다 bool aintSo = false;.

---

좋은 코드를 작성하는 방법을 배우는 가장 좋은 방법 중 하나는 좋은 코드를 읽는 것이므로 관심있는 일부 오픈 소스 프로젝트를 다운로드하고 코드베이스를 탐색하여 다른 사람들이하는 일을 볼 수 있습니다. "좋은 스타일이란 무엇인가"에 대한 답은 백만 가지가 있으며 명확한 합의가 항상 쉬운 것은 아닙니다.

The absolute best thing you can do to make things easier on the incoming programmers is to make sure you have good face-to-face communication skills. This can be easy or difficult depending on your own particular comfort and outgoingness and also on the other person in question. There are some things you can do to make it easier on both of you, be sure not to fall into the trap of communicating solely by email or code comments is a big one. If you have a report with the newcomer then they will come to you when they have questions instead of puzzling over code you created in a hurry and muttering to themselves.

That said, the best code is self-documenting. Use comments where necessary, particularly for method descriptions or tricky bits of business logic, but try to ensure the code itself is readable enough in most places. This enables you to avoid reducing code readability with too many comments.

A specific answer to your question, there are no need to rename simple counter variables such as i. In fact, i and x are commonly used in that situation in most c languages so anyone with familiarity with those languages will be very comfortable. Other variables, particularly class member variables and those used within methods, really require decent (though not too long) names.

---

Usually, the least useful is a variable (eg. counter), the shorter the name is. 'i' is quite a standard so don't worry about it. The important variables, though, as well as variables having a long life time should have a descriptive name.

As it has been said, be consistent (have all you vars to begin with a lowercase for example, choose to use or not to use underscores...).

Keep your function bodies less than 1 and a half page (except maybe for the main function), with descriptive and consistent name too.

And finally, comment the hacks, not the obvious :)

---

There is absolutely no substitute for working in a team, especially during the early years of your career.

The amount you can learn from other more experiences programmers is invaluable. There are several models of learning that suggest to reach the highest levels of ability (to be an expert) you have to be able to converse with other experts. Having peer relationships with those a few levels above you will help you learn far faster than reading books and websites will.

A lot of the other answers here are good, and give good resources for learning a lot of great stuff, but I'd make sure you're next job is with real people you can learn from.

---

I find ii to be far superior to i as my basic loop counter. I don't remember for sure, but I believe I learned that technique from Code Complete. Why is it superior? Try searching for i in your source. Then try searching for ii. See which works out better.

---

I've seen someone use Index, Indexx, Indexxx and so forth as counters. He now works for McDonalds.

To cut things short: I'd rather see i, j, k.

---

No their aren't any general standards.

Projects (or companies) usually set coding style guidelines for themselves. However being consistent is probably a rule followed by any style guideline.

---

For variables you're using for iteration, it's common to use 'i' or 'x' for the names. That won't bug most people -- if it does bug someone, then they probably haven't seen enough real code to qualify to do your job. :)

If you're really worried about what someone thinks of your code, then trying to name stuff consistently may not be a bad idea. On the other hand, don't go and risk breaking everything just cause of some obsession with making other people like your variable names, cause someone's gonna hate them no matter what you do. If it works, and it's documented well, and your variable names mean something (aside from the 'i' and 'x' variables mentioned above), then it's "good enough" IMO.

---

Conventions, comments and documentation are great, especially if you manage to explain what the programs are for and why you did things one way and not another.

If practical, I also suggest spending some face-to-face time explaining the projects to the new developers before you leave. That's invaluable.

---

I will be blunt here, but please have in mind that there is also a balance to be found.

Do what you are paid to do. Especially true for contractors. Do you force your style on others. Follow the company's coding standard and formatting standards.

Now if you are confident that the standard the company is using, is somehow wrong. You bring it up and explain first. Once a consensus is in place, you can use the new standard straight away and get a bonus (tap on shoulder) that you help keep the standards.

When in doubt, ask someone! Help you integrate with the existing team. When you become more senior, then others will come to you.

And a final word, the code belongs to the company that paid it and not the developer, so don't hold it like your baby.

---

If you must name "i" something different, call it "index". In a loop with as much (lack of) description as you've posted, that's the only appropriate name to use.

Sometimes when looping over a "blah" array, it's appropriate to call it a "blahIndex". This is especially true when there is more than one index being used against more than one data structure. A format like "blahIndex" will remind the mind which index goes with which item.

That said, it's a generally understood convention in the programming world that a variable called "i" is an index. That means that keeping "i" as-is shouldn't confuse anyone.

---

I've experienced a times where the original code guy put a project off by weeks because he didn't want to "expose" his code to another coder. That is all i remember about his code. And about him as a person.

---

OK, I'm going to be a contrarian here.

The reason everyone gets away with writing poorly commented code is that at the end of the day, few people ever go in and muck with it.

The real legacy for you to leave your company is programs that work well and do what the business folks need done.

How the code is written is much less important than whether it accomplishes something useful. The easiest program to maintain is the one that never needs to be changed because it does what people want it to do - no fuss, no muss, no bother.

ReferenceURL : https://stackoverflow.com/questions/2698530/how-do-i-make-my-code-easier-for-the-next-developer-to-understand