사람들이 자신의 코드를 댓글을달라고 설득하는 방법 [폐쇄

https://stackoverflow.com/questions/159597

03-07-2019
|

문제

다른 사람들이 자신의 코드를 댓글을달라고 설득하는 좋은 주장은 무엇입니까?

나는 많은 프로그래머들이 자신과 다른 사람들을위한 문서를 남기는 것에 대한 의견없이 코드 작성 속도를 선호한다는 것을 알았습니다. 내가 그들을 설득하려고 할 때 나는 "방법/클래스 이름이 그것이 무엇을하는지 말해야한다"등 반 구운 것들을들을 수있게된다.

당신이 댓글에 반대한다면, 당신은 그냥 의견을 남겨주세요. 이것은 사람들이 코드에 댓글을달라고 설득하려는 사람들에게 자원이어야합니다. :-)

다른 관련 질문은 다음과 같습니다. 주석 코드, 코드에 댓글을 달 수 있습니까? 그리고 당신의 의견은 어떻습니까?.

해결책

사람을 설득하는 가장 좋은 방법은 스스로 깨닫게하는 것입니다. 잘 댓글을 달린 코드를 디버그로 만드십시오. 그것은 그들에게 좋은 의견이 어떻게 보이는지 보여줄 것입니다. 댓글은 실제로 관련 정보를 전달하지 않는 한 (일반적으로 "이유")를 전달하지 않는 한 사용하지 않습니다. 그들은 그것이 얼마나 쉬운 지 알 것입니다. 그런 다음 기존 코드로 돌아가도록하십시오. 그들은 그것이 얼마나 힘든지 알 것입니다. 당신은 그들에게하지 말아야 할 일뿐만 아니라해야 할 일을 보여주었습니다 (이것은 더 중요합니다). 더 이상 할 필요가 없습니다. 더구나, 당신은 그들을 구두로 시도하고 설득 할 필요가 없습니다. 그들은 단순히 자신의 방식으로 코드를 댓글을 달아야 할 필요성을 이해해야합니다. 물론 이것은 댓글을 달아야 할 코드가 자기 설명이 아니라고 가정합니다.

다른 팁

"무엇"이 아닌 "왜"를 언급하십시오. 지금까지 나는 클래스 나 방법 또는 변수 이름에서 그것이 무엇을하는지, 무엇을 사용하는지에 동의해야한다. 댓글을 달지 않고 refactor.

이 접근 방식을 취하면 의견이 표시되며 유용한 의견을 얻게됩니다. 프로그래머는 왜 그들이 무언가를하는지 설명하는 것을 좋아합니다.

6 개월 전에 그들 자신의 코드를 보여주십시오. 그들이 2 ~ 4 분 안에 정확히 무엇을하는지 정확하게 이해할 수 없다면, 당신의 요점이 만들어 졌을 것입니다.

내 의견 :

나는하지 않을 것이다. 방법/클래스 이름은 그 일을 말해야합니다. 그렇지 않은 경우, 방법이나 클래스가 너무 많은 일을하려고하거나 불쌍한 이름입니다.

나는 왜 그런지에 대해 언급하는 팬입니다. 코드가 다른 접근 방식을 다른 접근 방식으로 사용하는 이유가 확실하지 않은 경우 댓글을 달아주십시오. 컴파일러 버그를 가져 오기 위해 해킹 미사용 변수를 추가 해야하는 경우 이유에 댓글을 달아주십시오. 그러나 "// 데이터베이스에 연결"과 같은 의견은 나쁜 코드 또는 나쁜 정책의 징후입니다. ConnectTodatabase ()라는 방법이 훨씬 좋습니다. "// DB Server IP를 결정하는 경우"가있는 경우 아마도 "deginedBeserVeripAddress ()"라는 메소드로 가져와야 할 것입니다.

디자인은 문서화 될 수 있지만 의견은 일반적으로 해당 수준의 문서화에 열악한 장소입니다. 디자인에 대한 지식과 이유에 대한 의견과 함께, 무엇을, 어떻게 분명 해야하는지에 대한 의견. 코드를 댓글을달라고 설득하기보다는 코드를 개선하도록 설득하는 것이 아니라면 그렇지 않은 경우.

아마도 그것은 단지 경험에서 배워야하는 것일 것입니다. 구체적으로, 6 개월 후 자신의 코드로 돌아 오는 경험, 그리고 당신이 그것을 썼을 때 당신이 생각한 것 (또는 당신이 무엇을하고 있는지)를 해결하려고 노력합니다. 그것은 확실히 의견이 그렇게 나쁜 생각이 아니라고 확신했습니다.

그들에게 리팩토러에게 약간의 끔찍하고 무례한 스파게티 코드를 제공하십시오. 변수가 논리적으로 명명되지 않은지 확인하십시오. 공백 선택 사항.

그리고 방법을보십시오 그들 좋아!

지나치게 가혹하지만 한 번에 두 점을 얻습니다.

코드를 잘 작성하십시오.
당신에게 댓글을 달아라 다른 사람 그것이 무엇을 의미하는지 알고 있습니다.

나는이 코드가 그들로부터 시작되어서는 안된다고 강조해야한다. 코멘트 ~이다 자신의 코드를 이해하는 데 정말 유용하지만 몇 달이 지났지 만 복잡한 부분을 이해하는 데 필수적입니다. 다른 사람들 암호. 그들은 다른 사람이 자신이하는 일을 이해해야 할 수도 있다는 것을 이해해야합니다.

하나의 최종 편집 : 댓글 품질 또한 매우 중요합니다. 일부 개발자는 자신의 작업에서 거의 2 : 1 코드 대 코드 비율을 가지고 있지만 좋은 의견은 아닙니다. 코드에 놀라 울 정도로 적은 의견을 가질 수 있지만 여전히 많은 의미가 있습니다.

설명 당신이하는 일. 코드 품질 ~해야 한다 그래도이 일의 대부분을 당신을 위해하십시오.
더 중요한 것은 설명하십시오 당신이 뭔가를하고있는 이유! 나는 개발자 (불행히도 대부분의 시간)가 왜 처음부터 좋은 아이디어라고 생각했는지 알지 못하는 일이없는 일이 정확히 무엇을하고 있는지에 대한 많은 코드를 보았습니다.

코드를 읽는 것이 코드가 무엇을 말할 수 있음을 상기시켜줍니다. 하다, 그것이 무엇인지 아닙니다 추정된 할 것.

귀하 또는 다른 개발자가 코드 완료를 읽지 않은 경우 (또는 코드 완료 2) 그럼 당신이하고있는 일을 멈추고 읽으십시오.

참가하는 한 가지는 "함수는 한 가지만 수행하고 잘 수행해야합니다"입니다. 그러한 함수의 이름을 따서 명명 된 경우, 댓글이 더 필요한 것은 무엇입니까?

의견은 설명해야 할 코드와 동기화되는 습관이 있습니다. 결과는 처음에 원래 의견을 갖지 않는 것보다 더 나빠질 수 있습니다. 뿐만 아니라 개발자 알다 그 의견은 나이가들 수 있고 신뢰할 수 없습니다. 그러므로 그들은 코드를 읽고 그것이 어쨌든 실제로하는 일을 스스로 분별할 것입니다! 이런 종류는 처음에 의견을 두는 요점을 무효화합니다.

함수 이름에서도 마찬가지라고 말하지만, 독창적 이었을지 모르지만 초과 근무는 이름에서 암시되지 않은 새로운 운영이 추가되었습니다.

모든 의견은 개발자가 함께 더 가까이있는 것을 선호하는 코드 라인을 분리하여 스크린 풀이 더 많이 볼 수 있도록하는 것 같습니다. 나는 내가 이해해야 할 많은 의견이있는 코드에 대한 내 자신의 재 활용을 알고 있습니다. 모든 주석을 삭제하십시오. 이제 코드가 무엇인지 알 수 있습니다.

시간이 끝나면 시간을 보내려면 일을 제대로 만들었습니다 당신의 시간은 코드를 댓글을 작성하는 것이 아니라 합리적으로 자기 설명을 보장하기 위해 코드를 리팩토링하는 데 훨씬 더 나은 소비입니다. 이러한 운동은 일반적인 코드 덩어리를 식별하는 것과 같은 다른 방식으로 지불합니다.

또한 많은 훌륭한 개발자들이 바삭 바삭한 깨끗한 C#, Java를 쓰는 것을 선호한다는 점을 염두에두고 있습니다. 상식을 가진 대부분의 사람들은 세부 사항이 얼마나 많은 세부 사항인지 알지만 훌륭한 개발자는 '대부분의 사람들'이 아닙니다. 그래서 우리는 같은 의견으로 끝납니다 \\adds a to b and store it in c (OK는 너무 극단적이지만 요점을 얻습니다).

그들이 싫어하는 일을하도록 요청하고 솔직히 잘하지 못한다 (옳은 일을 확신하더라도)은 이미 잃어버린 전투입니다.

나는 당신에게 멍청하지 않지만, 당신은 질문을 다시 표현해야합니다 다른 개발자가 팀으로 일하도록 어떻게 설득합니까?

진지하게, 어떤 사람들은 당신이 그들의 마음을 읽을 수 있다고 생각합니다.

민첩한 팀의 일원 인 경우 코드는 집합 적으로 소유되므로 코드를 읽지 않거나 읽기 어려운 코드를 볼 때 계속해서 변경 (리팩터)을 변경하십시오. 사람들이 불평한다면, 그들에게 이유를 말하고 선결제하십시오. 당신은 그것을 이해할 수 없다는 것을 알았고 아무도 코드를 소유하지 않습니다.

우리의 전략은 체계적인 코드 검토를하고 올바르게 문서화되지 않은 코드를 거부하는 것입니다 (주석, 적절한 기능 이름 지정 및 조직 등). 검토 자에게 명확하지 않으면 작업대 기간으로 돌아갑니다.

나는 "어제 당신의 코드 중 일부를 읽어야했다. 나는 그것을 이해할 수 있었지만 5 개의 잘 선택된 5 개의 해설 라인과는 그 목표를 달성 한 방법을 설명하는 5 개의 주석 라인과 같거나 같았다. -시간이 지났고 대신 문제를 이해하는 것에 대해 걱정할 수있었습니다. 나는 바보가 아니며 이해하기 어려운 것들을 쓸 수 있기 때문에 더 똑똑하지 않습니다. 반대로, 생산할 수 없다면 읽을 수있는 문서+코드 앙상블이면 개발자가 아닙니다. "

나는 이것을 오래 전에 나에게 뚫었습니다. 만약 당신이 무언가를 쓰고 합리적인 능력을 가진 사람이 그것을 이해할 수 없다면, 그것은 그의 잘못이 아니라 당신의 잘못입니다. 이는 자연 언어로 작성하는 데 적용되며 프로그래밍 언어로 작성하는 데 적용됩니다.

There have been similar discussions about commenting. Here's the one on what rules people follow when commenting code: What are your "hard rules" about commenting your code?. Some of the answers have also very good reasons why you would want to comment your code.

Show wisdom in your desire for comments, and they will be more likely to listen.

Less is more.

Emphasize quality over quantity.

In my team, there was a push to comment everything in certain API's. Some developers began using a tool that would automatically generate comments by looking at the method names and signatures.

For example:

/// <summary>
/// Gets the Person.
/// </summary>
/// <returns>
/// A Person
/// </returns>
public Person GetPerson()
{

}

Can you think of a bigger waste of screen real estate? Can you think of a bigger waste of brain cycles than reading comments that provide no new information?

If it is obvious from the method signature, don't say it! If I can figure it out in a few seconds, don't put it in a comment. As others have put it, tell me why you chose to do it that way, not what you did. Write your code so that it is obvious what it does.

Lead by example. Developers are easily swayed when they see The Right Thing, so seeing solid practices in action may encourage them to do the same. Additionally, you could encourage your group to adopt code metrics that address code maintainability and comments. For example, Code Analysis will produce a bug for methods without summary documentation.

The current coding standards at my current place of work is to comment every function. Blanked rules like this are harmful, and should never be in place. There are situations (and some of them common) where adding comments removes readability.

class User {
    getUserName() { /* code here */ }
}

What is the point in adding a function header to the above peice of code? What else are you going to say besdies "gets the username". Not all code needs to be commented. My rule of thumb is: skip the comments if you are not adding any useful information that the function signature does not.

Comments should be thorough, written at the level of intent (why not how), and rare.

When writing code I tend to comment reasonably heavily as a matter of course. Then, I go back through and try to delete as many comments as possible, without decreasing the understandability of the code. >80% of the time this is as easy as extracting a well named method, this usually results in a comment which merely duplicates the information in the code itself. Beyond that, if there's a section of code that "needs" a comment I look for ways to simplify it or make it clearer.

Code should be self-documenting, and with the right techniques you can get 95% of the way there pretty easily. Generally I consider it to be a failure if there are any comments remaining on code that I check in.

Depends on how much power you have...

I found a very effective way was to make it a fixed part of peer based code reviews - points for comments. If there was a remark that the code was badly commented I would make the developer comment it to my satisfaction, which basically meanth they had to describe enough of the code for me to understand it by printing it out and reading it. And I would do it too.

Remarkably this was popular with the developers, even though it sounds dickensian. Two things happened. First, people started to comment their code. Second, badly commented code became a sign that the developer didn't quite understand what they had written (otherwise they would have described it).

The only real downside was that the comments had to be kept up with the code when it was revised for bug-fixes etc. This was almost impossible to enforce in a real development shop, but once enough good practice was engrained it sort of happened naturally.

BTW I prefer comments in the code itself rather than a Dostoevsky novel as a doc string. The former is a useful aid to subsequent programmers. The latter is just a long piece of out of date text that fills up the docs and misleads everyone.

Have them use an unfamiliar API, but do the programming on a non-Internet connected machine(if you can find them these days) so that they don't have any access to the API documentation. This is effectively what they are forcing other developers to do if they are trying to use the code of the non-documenters!

You also have to differentiate two different comments here:

API comments (javadoc or other similar kind of documentation): you can ask for them to use their own code in a limit scenario (boundary conditions like null objects or empty strings or...) and see if they actually manage to remember what does their own functions in those case
(That is why I am for a complete javadoc including limit-value)
Internal comments (within the source code): you can ask them to explain any function they have coded, just pick a function with a really high cyclomatic complexity level, and see them struggle around all the different code workflows and decision branching ;)

Well, there's always the "if you don't comment your code, we'll find someone else who'll comment theirs" approach.

More gently, tell them that they are sorely letting down the team if they don't document and comment what they are doing. The code does NOT belong to the individual, unless they are complete lone wolves. It belongs to the team, the group, whether that be a company or a community.

"Writing Code" = "Writing sequence of commands in a special language" + "Writing comments"

It shall be self-evident to comment code while writing it! Have you ever commented code that is already 3 or 4 months old? (Of course you have, and it was everything else but fun!)

If your project is already well documented, programmers who add new code may be motivated to write comments in a similar manner.

@James Curran I 100% agree! I can read your code and figure out what you told the compiler to do; but that doesn't mean it was your intent to make the compiler do that. I know I'm not an arrogent enough programmer to believe that everytime I write code it does exactly what I was trying to make it do. Additionally, I often find it helps me catch silly logic errors in my code by going through after I've written it and trying to explain what I intended for the code to do.

One idea is to point out that it takes less than a minute to write one or two sentences per class and less than half a minute to write one sentence per method.

Tell them to document their functions and interfaces with Javadoc commments and then to run the code through Doxygen to generate cool-looking HTML documentation for their code. The coolness factor can be a good motivator sometimes.

I use one subtle technique:

I set the level of warnings in the project to be reported as errors. And our Continuous Integration server is building the whole solution along with XML documentation upon each ckeck-in.

If developers do not write the comments, the build fails! And after that, they have to write the comments, so after a while, they got used to it.

It isn't aggressive in terms of pressure, but i find it like nice way to correct their behavior.

If developers have to take part in code reviews and are exposed to good commenting they should be able to get the clue. If they do not see the practice as useful then they should get some feedback from their peer reviewers.

Failing that (assuming you're the supervisor / manager) make it part of their performance appraisal. If you can measure it, you can appraise based on it.

Ensure that it's a REVIEWED commenting that you score on, as the passive-aggressive devs will document every last statement as a not-so-subtle FU.

I've become a firm believer in what I call Headrick's Rule, named for a coworker of mine who discovered that a good way to motivate someone to do something is to make it painful for them not to do it.

In your case, asking your non-commenting developers to spend an hour or two explaining their code, perhaps to a "slow" audience, perhaps during their lunch hour "to avoid project slippage" will go a long way. Smart people--even stubborn ones--learn fast!

In my opinion (and I'm talking about .Net programming here) if you have to put a comment you have failed in making the code readable. The answer is usually refactor!

However, if you feel you have to put a comment then it should always be a "why" type of comment and not a comment that explains what the code does.

Writing down what a method / class will do before actually coding it helps a lot to get it right - and you have commented it.

Only employ good engineers who ensure their code implicitly states the intention (using comments and otherwise). Anyone who wants a job will have to do it right. Harsh, but fair, IMHO.

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

제휴하지 않습니다 StackOverflow