Skip to main content
added 294 characters in body
Source Link
Aaron Hall
  • 6k
  • 4
  • 27
  • 47

The question:

Given all this is it even possible to write good coding standards that capture this idea? Ones that will be relevant in a peer review but won't turn into a mindless checklist activity that produce notes no more helpful than: "You forgot to comment on line 42".

Comments should not seek to educate the reader on the language. A reader should be assumed to know the language better than the writer, but with much less context than the writer.

A reader of this code, from your example, should know that exit() will exit the application - thus making the comment redundant:

/* Exit the application */
exit();

Redundant comments are a violation of DRY, and changes to the code do not necessarily propagate to the comments, leaving comments that do not reflect what the code is actually doing.

However, comments that explain why you're doing something may be valuable - especially if you can't easily communicate the meaning in the code itself.

Python's PEP 8 (the style guide for Python in the CPython standard library) provides the following guideline for inline comments:

Use inline comments sparingly.

An inline comment is a comment on the same line as a statement. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space.

Inline comments are unnecessary and in fact distracting if they state the obvious. Don't do this:

x = x + 1                 # Increment x

But sometimes, this is useful:

x = x + 1                 # Compensate for border

Given such an example, I personally prefer to go a step further and would try to eliminate this comment as well. For example, I might arrive at:

border_compensation = 1
compensated_x = x + border_compensation

Making your code self-documenting is not a new idea.

Back to the actual question:

Given all this is it even possible to write good coding standards that capture this idea?

I believe that the PEP 8 guidance and example demonstrates a good coding standard that captures this idea. So yes, I believe it is possible.

Given all this is it even possible to write good coding standards that capture this idea? Ones that will be relevant in a peer review but won't turn into a mindless checklist activity that produce notes no more helpful than: "You forgot to comment on line 42".

Comments should not seek to educate the reader on the language. A reader should be assumed to know the language better than the writer, but with much less context than the writer.

A reader of this code, from your example, should know that exit() will exit the application - thus making the comment redundant:

/* Exit the application */
exit();

Redundant comments are a violation of DRY, and changes to the code do not necessarily propagate to the comments, leaving comments that do not reflect what the code is actually doing.

However, comments that explain why you're doing something may be valuable - especially if you can't easily communicate the meaning in the code itself.

Python's PEP 8 (the style guide for Python in the CPython standard library) provides the following guideline for inline comments:

Use inline comments sparingly.

An inline comment is a comment on the same line as a statement. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space.

Inline comments are unnecessary and in fact distracting if they state the obvious. Don't do this:

x = x + 1                 # Increment x

But sometimes, this is useful:

x = x + 1                 # Compensate for border

Given such an example, I personally prefer to go a step further and would try to eliminate this comment as well. For example, I might arrive at:

border_compensation = 1
compensated_x = x + border_compensation

Making your code self-documenting is not a new idea.

The question:

Given all this is it even possible to write good coding standards that capture this idea? Ones that will be relevant in a peer review but won't turn into a mindless checklist activity that produce notes no more helpful than: "You forgot to comment on line 42".

Comments should not seek to educate the reader on the language. A reader should be assumed to know the language better than the writer, but with much less context than the writer.

A reader of this code, from your example, should know that exit() will exit the application - thus making the comment redundant:

/* Exit the application */
exit();

Redundant comments are a violation of DRY, and changes to the code do not necessarily propagate to the comments, leaving comments that do not reflect what the code is actually doing.

However, comments that explain why you're doing something may be valuable - especially if you can't easily communicate the meaning in the code itself.

Python's PEP 8 (the style guide for Python in the CPython standard library) provides the following guideline for inline comments:

Use inline comments sparingly.

An inline comment is a comment on the same line as a statement. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space.

Inline comments are unnecessary and in fact distracting if they state the obvious. Don't do this:

x = x + 1                 # Increment x

But sometimes, this is useful:

x = x + 1                 # Compensate for border

Given such an example, I personally prefer to go a step further and would try to eliminate this comment as well. For example, I might arrive at:

border_compensation = 1
compensated_x = x + border_compensation

Making your code self-documenting is not a new idea.

Back to the actual question:

Given all this is it even possible to write good coding standards that capture this idea?

I believe that the PEP 8 guidance and example demonstrates a good coding standard that captures this idea. So yes, I believe it is possible.

Source Link
Aaron Hall
  • 6k
  • 4
  • 27
  • 47

Given all this is it even possible to write good coding standards that capture this idea? Ones that will be relevant in a peer review but won't turn into a mindless checklist activity that produce notes no more helpful than: "You forgot to comment on line 42".

Comments should not seek to educate the reader on the language. A reader should be assumed to know the language better than the writer, but with much less context than the writer.

A reader of this code, from your example, should know that exit() will exit the application - thus making the comment redundant:

/* Exit the application */
exit();

Redundant comments are a violation of DRY, and changes to the code do not necessarily propagate to the comments, leaving comments that do not reflect what the code is actually doing.

However, comments that explain why you're doing something may be valuable - especially if you can't easily communicate the meaning in the code itself.

Python's PEP 8 (the style guide for Python in the CPython standard library) provides the following guideline for inline comments:

Use inline comments sparingly.

An inline comment is a comment on the same line as a statement. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space.

Inline comments are unnecessary and in fact distracting if they state the obvious. Don't do this:

x = x + 1                 # Increment x

But sometimes, this is useful:

x = x + 1                 # Compensate for border

Given such an example, I personally prefer to go a step further and would try to eliminate this comment as well. For example, I might arrive at:

border_compensation = 1
compensated_x = x + border_compensation

Making your code self-documenting is not a new idea.