Post Made Community Wiki by Danubian Sailor
2 added 303 characters in body
source | link

I find that code review is a fantastic process for answering this question in concrete ways. If I read someone's pull request (putting forth actual effort to read it, not just glancing at it with the attitude that everything must be immediately apparent) and can't understand what it does, I tell people to add a comment. Or you can do this by yourself with a rubber duck.

Most people inuititively know what ideas needs to be commented - It's whatever you would say to someone standing next to you if they asked you a question about the code. Often I'll ask someone to explain something in a review, they'll give a great answer, and my response is "Copy that explanation you just wrote into a comment in the code."

But for some reason that's rarely the content that people end up writing in their comments. Instead people write inane stuff like

/**
 * Gets the {@link List} of {@link Author}s for the given {@link Book}.
 *
 * @param book The {@link Book} for which you want the {@link Author}s.
 * @return All of the {@link Author}s for the given {@link Book}.
 */
List<Author> getAuthors(Book book) { ...

and

// increment i by 1
i += 1

and that's the kind of stuff that the experienced coworkers are reacting to. I myself tell people when I'm reviewing code to remove these sorts of low-level comments that add no more information than can be found in the immediately surrounding lines.

One prime example of a trivial thing that does need to be commented is descriptions of duck types in dynamic languages. If a function's argument or return value is a dict with a bunch of properties on it, you're in for some insanity later on if you don't comment exactly what those properties are.

No amount of commenting will raise any nontrivial code to the level that an 8-year-old could understand, so you shouldn't try. You have to make some assumptions that the reader knows how to read the code, because otherwise it's a completely futile effort.

Finally, comments are very often wrong. People often skip over them when reading, and don't update them when things change. You can't write a unit test for your comments, so only the way to defend your code against the rot that occurs when your careless coworkers start monkeying with it is to comment only the ideas are are essential. Comments that don't add value add negative value when they become erroneous.

Document design, ideas, architecture, history, rationale - not lines of code.

I find that code review is a fantastic process for answering this question in concrete ways. If I read someone's pull request (putting forth actual effort to read it, not just glancing at it with the attitude that everything must be immediately apparent) and can't understand what it does, I tell people to add a comment. Or you can do this by yourself with a rubber duck.

Most people inuititively know what ideas needs to be commented - It's whatever you would say to someone standing next to you if they asked you a question about the code. Often I'll ask someone to explain something in a review, they'll give a great answer, and my response is "Copy that explanation you just wrote into a comment in the code."

But for some reason that's rarely the content that people end up writing in their comments. Instead people write inane stuff like

/**
 * Gets the {@link List} of {@link Author}s for the given {@link Book}.
 *
 * @param book The {@link Book} for which you want the {@link Author}s.
 * @return All of the {@link Author}s for the given {@link Book}.
 */
List<Author> getAuthors(Book book) { ...

and

// increment i by 1
i += 1

and that's the kind of stuff that the experienced coworkers are reacting to. I myself tell people when I'm reviewing code to remove these sorts of low-level comments that add no more information than can be found in the immediately surrounding lines.

No amount of commenting will raise any nontrivial code to the level that an 8-year-old could understand, so you shouldn't try. You have to make some assumptions that the reader knows how to read the code, because otherwise it's a completely futile effort.

Finally, comments are very often wrong. People often skip over them when reading, and don't update them when things change. You can't write a unit test for your comments, so only the way to defend your code against the rot that occurs when your careless coworkers start monkeying with it is to comment only the ideas are are essential. Comments that don't add value add negative value when they become erroneous.

Document design, ideas, architecture, history, rationale - not lines of code.

I find that code review is a fantastic process for answering this question in concrete ways. If I read someone's pull request (putting forth actual effort to read it, not just glancing at it with the attitude that everything must be immediately apparent) and can't understand what it does, I tell people to add a comment. Or you can do this by yourself with a rubber duck.

Most people inuititively know what ideas needs to be commented - It's whatever you would say to someone standing next to you if they asked you a question about the code. Often I'll ask someone to explain something in a review, they'll give a great answer, and my response is "Copy that explanation you just wrote into a comment in the code."

But for some reason that's rarely the content that people end up writing in their comments. Instead people write inane stuff like

/**
 * Gets the {@link List} of {@link Author}s for the given {@link Book}.
 *
 * @param book The {@link Book} for which you want the {@link Author}s.
 * @return All of the {@link Author}s for the given {@link Book}.
 */
List<Author> getAuthors(Book book) { ...

and

// increment i by 1
i += 1

and that's the kind of stuff that the experienced coworkers are reacting to. I myself tell people when I'm reviewing code to remove these sorts of low-level comments that add no more information than can be found in the immediately surrounding lines.

One prime example of a trivial thing that does need to be commented is descriptions of duck types in dynamic languages. If a function's argument or return value is a dict with a bunch of properties on it, you're in for some insanity later on if you don't comment exactly what those properties are.

No amount of commenting will raise any nontrivial code to the level that an 8-year-old could understand, so you shouldn't try. You have to make some assumptions that the reader knows how to read the code, because otherwise it's a completely futile effort.

Finally, comments are very often wrong. People often skip over them when reading, and don't update them when things change. You can't write a unit test for your comments, so only the way to defend your code against the rot that occurs when your careless coworkers start monkeying with it is to comment only the ideas are are essential. Comments that don't add value add negative value when they become erroneous.

Document design, ideas, architecture, history, rationale - not lines of code.

1
source | link

I find that code review is a fantastic process for answering this question in concrete ways. If I read someone's pull request (putting forth actual effort to read it, not just glancing at it with the attitude that everything must be immediately apparent) and can't understand what it does, I tell people to add a comment. Or you can do this by yourself with a rubber duck.

Most people inuititively know what ideas needs to be commented - It's whatever you would say to someone standing next to you if they asked you a question about the code. Often I'll ask someone to explain something in a review, they'll give a great answer, and my response is "Copy that explanation you just wrote into a comment in the code."

But for some reason that's rarely the content that people end up writing in their comments. Instead people write inane stuff like

/**
 * Gets the {@link List} of {@link Author}s for the given {@link Book}.
 *
 * @param book The {@link Book} for which you want the {@link Author}s.
 * @return All of the {@link Author}s for the given {@link Book}.
 */
List<Author> getAuthors(Book book) { ...

and

// increment i by 1
i += 1

and that's the kind of stuff that the experienced coworkers are reacting to. I myself tell people when I'm reviewing code to remove these sorts of low-level comments that add no more information than can be found in the immediately surrounding lines.

No amount of commenting will raise any nontrivial code to the level that an 8-year-old could understand, so you shouldn't try. You have to make some assumptions that the reader knows how to read the code, because otherwise it's a completely futile effort.

Finally, comments are very often wrong. People often skip over them when reading, and don't update them when things change. You can't write a unit test for your comments, so only the way to defend your code against the rot that occurs when your careless coworkers start monkeying with it is to comment only the ideas are are essential. Comments that don't add value add negative value when they become erroneous.

Document design, ideas, architecture, history, rationale - not lines of code.