Skip to main content
deleted 33 characters in body
Source Link
candied_orange
  • 114.5k
  • 27
  • 222
  • 352

There are two different things you allude to when you talk about comments. They're not the same, and and the distinction is important.

Documentation tells you about the outward-facing bits of a piece of code - its interface.

Typically tooling will allow you to read them in a 'standalone' fashion, i.e. you're not looking at at the underlying code at the same time.

All the interface should be documented (e.g. each method, excluding private methods), and it should should describe inputs, outputs, and any other expectations, limitations, etc., especially things which which can't be expressed through constraints, tests, etc. (Exactly how much detail and where it goes depends on the project).

Good documentation allows the potential consumer to decide whether, when, and how to use the code.

Comments in source code have a different purpose. They are there for people looking at the source source code. They primrilyprimarily describe the implementation.

Comments are always read in amongst the underlying code.

Comments should explain surprising decisions or complex algorithms, or of options not taken (and reasoning reasoning). They are there so future developers can understand the thought processes of their predecessors predecessors, and have at hand information which they otherwise might overlook or spend much time seeking seeking, e.g.

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

You cannot infer anything from the absence of a comment, and the comment may of course be as wrong wrong as the surrounding code or more so. Judgement must be exercised both on the part of the author author and on the part of the reader.

Commenting every line is clearly more work of questionable additional value, which comes with an opportunity opportunity cost. If you have a rule that says every line must be commented, you will get that, but but at the expense of important parts being commented well.

But it's worse than that: the purpose of a comment is defeated if every line is commented. Comments Comments become noise which make code hard to read: obscuring rather than clarifying. Moreover, indiscriminate indiscriminate commenting makes the truly important comments harder to spot.

Neither comments nor documentation provide any sort of measure or guarantee of the quality of code code they describe; they are not a replacement for genuine QA. Their purpose is forward-looking, i i.e. in the hope that they will help those who interact with it avoid making mistakes.

In summary, your coding standards can and should require documentation (automated checks help spot undocumented functions functions/methods, but humans still need to check if the documentation is any good). Comments are a judgement call, and your style guide should acknowledge this. Those who never comment comment, and those who comment without thinking should expect to be challenged.

There are two different things you allude to when you talk about comments. They're not the same, and the distinction is important.

Documentation tells you about the outward-facing bits of a piece of code - its interface.

Typically tooling will allow you to read them in a 'standalone' fashion, i.e. you're not looking at the underlying code at the same time.

All the interface should be documented (e.g. each method, excluding private methods), and it should describe inputs, outputs, and any other expectations, limitations, etc., especially things which can't be expressed through constraints, tests, etc. (Exactly how much detail and where it goes depends on the project).

Good documentation allows the potential consumer to decide whether, when, and how to use the code.

Comments in source code have a different purpose. They are there for people looking at the source code. They primrily describe the implementation.

Comments are always read in amongst the underlying code.

Comments should explain surprising decisions or complex algorithms, or of options not taken (and reasoning). They are there so future developers can understand the thought processes of their predecessors, and have at hand information which they otherwise might overlook or spend much time seeking, e.g.

# 'map' outperforms 'for' here by a factor of 10

// This line works around an obscure bug in IE10, see issue #12053

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

You cannot infer anything from the absence of a comment, and the comment may of course be as wrong as the surrounding code or more so. Judgement must be exercised both on the part of the author and on the part of the reader.

Commenting every line is clearly more work of questionable additional value, which comes with an opportunity cost. If you have a rule that says every line must be commented, you will get that, but at the expense of important parts being commented well.

But it's worse than that: the purpose of a comment is defeated if every line is commented. Comments become noise which make code hard to read: obscuring rather than clarifying. Moreover, indiscriminate commenting makes the truly important comments harder to spot.

Neither comments nor documentation provide any sort of measure or guarantee of the quality of code they describe; they are not a replacement for genuine QA. Their purpose is forward-looking, i.e. in the hope that they will help those who interact with it avoid making mistakes.

In summary, your coding standards can and should require documentation (automated checks help spot undocumented functions/methods, but humans still need to check if the documentation is any good). Comments are a judgement call, and your style guide should acknowledge this. Those who never comment, and those who comment without thinking should expect to be challenged.

There are two different things you allude to when you talk about comments. They're not the same, and the distinction is important.

Documentation tells you about the outward-facing bits of a piece of code - its interface.

Typically tooling will allow you to read them in a 'standalone' fashion, i.e. you're not looking at the underlying code at the same time.

All the interface should be documented (e.g. each method, excluding private methods), and it should describe inputs, outputs, and any other expectations, limitations, etc., especially things which can't be expressed through constraints, tests, etc. (Exactly how much detail and where it goes depends on the project).

Good documentation allows the potential consumer to decide whether, when, and how to use the code.

Comments in source code have a different purpose. They are there for people looking at the source code. They primarily describe the implementation.

Comments are always read in amongst the underlying code.

Comments should explain surprising decisions or complex algorithms, or of options not taken (and reasoning). They are there so future developers can understand the thought processes of their predecessors, and have at hand information which they otherwise might overlook or spend much time seeking, e.g.

# 'map' outperforms 'for' here by a factor of 10  

// This line works around an obscure bug in IE10, see issue #12053  

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

You cannot infer anything from the absence of a comment, and the comment may of course be as wrong as the surrounding code or more so. Judgement must be exercised both on the part of the author and on the part of the reader.

Commenting every line is clearly more work of questionable additional value, which comes with an opportunity cost. If you have a rule that says every line must be commented, you will get that, but at the expense of important parts being commented well.

But it's worse than that: the purpose of a comment is defeated if every line is commented. Comments become noise which make code hard to read: obscuring rather than clarifying. Moreover, indiscriminate commenting makes the truly important comments harder to spot.

Neither comments nor documentation provide any sort of measure or guarantee of the quality of code they describe; they are not a replacement for genuine QA. Their purpose is forward-looking, i.e. in the hope that they will help those who interact with it avoid making mistakes.

In summary, your coding standards can and should require documentation (automated checks help spot undocumented functions/methods, but humans still need to check if the documentation is any good). Comments are a judgement call, and your style guide should acknowledge this. Those who never comment, and those who comment without thinking should expect to be challenged.

Source Link
user52889
  • 1.7k
  • 11
  • 13

There are two different things you allude to when you talk about comments. They're not the same, and the distinction is important.

Documentation tells you about the outward-facing bits of a piece of code - its interface.

Typically tooling will allow you to read them in a 'standalone' fashion, i.e. you're not looking at the underlying code at the same time.

All the interface should be documented (e.g. each method, excluding private methods), and it should describe inputs, outputs, and any other expectations, limitations, etc., especially things which can't be expressed through constraints, tests, etc. (Exactly how much detail and where it goes depends on the project).

Good documentation allows the potential consumer to decide whether, when, and how to use the code.

Comments in source code have a different purpose. They are there for people looking at the source code. They primrily describe the implementation.

Comments are always read in amongst the underlying code.

Comments should explain surprising decisions or complex algorithms, or of options not taken (and reasoning). They are there so future developers can understand the thought processes of their predecessors, and have at hand information which they otherwise might overlook or spend much time seeking, e.g.

# 'map' outperforms 'for' here by a factor of 10

// This line works around an obscure bug in IE10, see issue #12053

-- We are going to recursively find the parents up to and including the root node.
-- We will then calculate the number of steps from leaf node to root node.
-- We first use a WITH clause to get the ID of the root node.

You cannot infer anything from the absence of a comment, and the comment may of course be as wrong as the surrounding code or more so. Judgement must be exercised both on the part of the author and on the part of the reader.

Commenting every line is clearly more work of questionable additional value, which comes with an opportunity cost. If you have a rule that says every line must be commented, you will get that, but at the expense of important parts being commented well.

But it's worse than that: the purpose of a comment is defeated if every line is commented. Comments become noise which make code hard to read: obscuring rather than clarifying. Moreover, indiscriminate commenting makes the truly important comments harder to spot.

Neither comments nor documentation provide any sort of measure or guarantee of the quality of code they describe; they are not a replacement for genuine QA. Their purpose is forward-looking, i.e. in the hope that they will help those who interact with it avoid making mistakes.

In summary, your coding standards can and should require documentation (automated checks help spot undocumented functions/methods, but humans still need to check if the documentation is any good). Comments are a judgement call, and your style guide should acknowledge this. Those who never comment, and those who comment without thinking should expect to be challenged.