Return to Answer

Comment every line of code? No.

The purpose of the others rules you talk about is precisely to avoid that.

Comments to a readable code are at best redundant, and at worst will throw a reader off looking for the non-existent purpose of the comment.

If you comment whole code which is self-explanatory, you double the amount of reading with out giving any additional information. I am not sure if such redundancy would pay off. One can imagine a reviewer saying that 42 says "display_error" while the comment says "displays warning". But imagine a change in the code. You have two places to correct now. It becomes clear this style has copy-paste negatives.

I would say that optimally the code should not need any comments, other than documentation.

There are styles which go total opposite, if you have doubts about line it's either:

1. The code is too complicated and should be refactored into a function with a name with a semantic meaning for the portion of code. Be it a complex if or a portion of an algorithm. (Or a clever LINQ one-liner)

2. If it cannot be simplified, you don't know enough idioms of language.

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

As for the process. Our standard gave quite much credit to the reviewer. Assuming they are not malicious this works good.

When he asks "What is variable o?", you rename it. If he asks what does this block do, either refactor or comment. If there was a debate whether something is clear or not, if the reviewer did not get it, then by definition it is not. On very rare occasions there was something like 2nd opinion from few friends.

On average, you should get a code understandable by the average programmer in the team. IMO it keeps off the redundant information, and ensures that the code is understandable by at least one other member of the team, which we found a good optimum.

Also, there were no absolutes. Though we were a small group. It's easy to find consensus in group of 5.

Comment every line of code? No.

The purpose of the others rules you talk about is precisely to avoid that.

Comments to a readable code are at best redundant, and at worst will throw a reader off looking for the non-existent purpose of the comment.

If you comment whole code which is self-explanatory, you double the amount of reading with out giving any additional information. I am not sure if such redundancy would pay off. One can imagine a reviewer saying that 42 says "display_error" while the comment says "displays warning". But imagine a change in the code. You have two places to correct now. It becomes clear this style has copy-paste negatives.

I would say that optimally the code should not need any comments, other than documentation.

There are styles which go total opposite, if you have doubts about line it's either:

1. The code is too complicated and should be refactored into a function with a name with a semantic meaning for the portion of code. Be it a complex if or a portion of an algorithm. (Or a clever LINQ one-liner)

2. If it cannot be simplified, you don't know enough idioms of language.

(I personally am not a fanatic of strict no-comments rule, but I find it as a good initial mindset to go by.)

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

As for the process. Our standard gave quite much credit to the reviewer. Assuming they are not malicious this works good.

When he asks "What is variable o?", you rename it. If he asks what does this block do, either refactor or comment. If there was a debate whether something is clear or not, if the reviewer did not get it, then by definition it is not. On very rare occasions there was something like 2nd opinion from few friends.

On average, you should get a code understandable by the average programmer in the team. IMO it keeps off the redundant information, and ensures that the code is understandable by at least one other member of the team, which we found a good optimum.

Also, there were no absolutes. Though we were a small group. It's easy to find consensus in group of 5.

Comment every line of code? No.

The purpose of the others rules you talk about is precisely to avoid that.

Comments to a readable code are at best redundant, and at worst will throw a reader off looking for the non-existent purpose of the comment.

If you comment whole code which is self-explanatory, you double the amount of reading with out giving any additional information. I am not sure if such redundancy would pay off. One can imagine a reviewer saying that 42 says "display_error" while the comment says "displays warning". But imagine a change in the code. You have two places to correct now. It becomes clear this style has copy-paste negatives.

I would say that optimally the code should not need any comments, other than documentation.

There are styles which go total opposite, if you have doubts about line it's either:

1. The code is too complicated and should be refactored into a function with a name with a semantic meaning for the portion of code. Be it a complex if or a portion of an algorithm.

2. If it cannot be simplified, you don't know enough idioms of language.

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

As for the process. Our standard gave quite much credit to the reviewer. Assuming they are not malicious this works good. Also, there were no absolutes.

When he asks "What is variable o?", you rename it. If he asks what does this block do, either refactor or comment. If there was a debate whether something is clear or not, if the reviewer did not get it, then by definition it is not. On very rare occasions there was something like 2nd opinion from few friends.

On average, you should get a code understandable by the average programmer in the team. IMO it keeps off the redundant information, and ensures that the code is understandable by at least one other member of the team, which we found a good optimum.

Comment every line of code? No.

The purpose of the others rules you talk about is precisely to avoid that.

Comments to a readable code are at best redundant, and at worst will throw a reader off looking for the non-existent purpose of the comment.

If you comment whole code which is self-explanatory, you double the amount of reading with out giving any additional information. I am not sure if such redundancy would pay off. One can imagine a reviewer saying that 42 says "display_error" while the comment says "displays warning". But imagine a change in the code. You have two places to correct now. It becomes clear this style has copy-paste negatives.

I would say that optimally the code should not need any comments, other than documentation.

There are styles which go total opposite, if you have doubts about line it's either:

1. The code is too complicated and should be refactored into a function with a name with a semantic meaning for the portion of code. Be it a complex if or a portion of an algorithm. (Or a clever LINQ one-liner)

2. If it cannot be simplified, you don't know enough idioms of language.

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

As for the process. Our standard gave quite much credit to the reviewer. Assuming they are not malicious this works good.

When he asks "What is variable o?", you rename it. If he asks what does this block do, either refactor or comment. If there was a debate whether something is clear or not, if the reviewer did not get it, then by definition it is not. On very rare occasions there was something like 2nd opinion from few friends.

On average, you should get a code understandable by the average programmer in the team. IMO it keeps off the redundant information, and ensures that the code is understandable by at least one other member of the team, which we found a good optimum.

Also, there were no absolutes. Though we were a small group. It's easy to find consensus in group of 5.

Comment every line of code? No.

The purpose of the others rules you talk about is precisely to avoid that.

Comments to a readable code are at best redundant, and at worst will throw a reader off looking for the non-existent purpose of the comment.

If you comment whole code which is self-explanatory, you double the amount of reading with out giving any additional information. I am not sure if such redundancy would pay off. One can imagine a reviewer saying that 42 says "display_error" while the comment says "displays warning". But imagine a change in the code. You have two places to correct now. It becomes clear this style has copy-paste negatives.

I would say that optimally the code should not need any comments, other than documentation.

There are styles which go total opposite, if you have doubts about line it's either:

1. The code is too complicated and should be refactored into a function with a name with a semantic meaning for the portion of code. Be it a complex if or a portion of an algorithm.

2. You don't know enough idioms of language if it cannot be simplified.

As for the process. The best I was part of, was to trust your colleague, the reviewer. When he asks "What is variable o? " you rename it. If he asks what does this block do, either refactor or comment.

On average, you should get a code understandable by the average programmer in the team. IMO it keeps off the redundant information, and ensures that the code is understandable by at least one other member of the team, which we foudn a good optimum.

Comment every line of code? No.

The purpose of the others rules you talk about is precisely to avoid that.

Comments to a readable code are at best redundant, and at worst will throw a reader off looking for the non-existent purpose of the comment.

If you comment whole code which is self-explanatory, you double the amount of reading with out giving any additional information. I am not sure if such redundancy would pay off. One can imagine a reviewer saying that 42 says "display_error" while the comment says "displays warning". But imagine a change in the code. You have two places to correct now. It becomes clear this style has copy-paste negatives.

I would say that optimally the code should not need any comments, other than documentation.

There are styles which go total opposite, if you have doubts about line it's either:

1. The code is too complicated and should be refactored into a function with a name with a semantic meaning for the portion of code. Be it a complex if or a portion of an algorithm.

2. If it cannot be simplified, you don't know enough idioms of language.

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

As for the process. Our standard gave quite much credit to the reviewer. Assuming they are not malicious this works good. Also, there were no absolutes.

When he asks "What is variable o?", you rename it. If he asks what does this block do, either refactor or comment. If there was a debate whether something is clear or not, if the reviewer did not get it, then by definition it is not. On very rare occasions there was something like 2nd opinion from few friends.

On average, you should get a code understandable by the average programmer in the team. IMO it keeps off the redundant information, and ensures that the code is understandable by at least one other member of the team, which we found a good optimum.