There are two ways to communicate what your code does: the code itself and using comments.
Self Documenting Code
Source code should be understandable not because it has comments but because of its elegance and clarity – correct use of variable names, good use of whitespace, good separation of logic, and concise readability. Code will be read hundreds of times and written only a few times. So invest quality time into spelling out names such as fn into firstname. Fight the urge to use cryptic variable names.
Code Comments
Code should have comments however an abundance of comments can be just as bad as too few. Comments should explain why something is done. The code itself already shows what it is done. So commenting on what is done is redundant. Do not use commenting as a substitute for good code. Another way to say that is that if you need to comment code due to its unclarity then maybe you need to rewrite the code to be more clear and remove the comment.
I found this article which is about using natural language in your code to make it more readable. http://jamesgolick.com/2008/1/14/taking-style-tips-from-natural-language
Self Documenting Code
Source code should be understandable not because it has comments but because of its elegance and clarity – correct use of variable names, good use of whitespace, good separation of logic, and concise readability. Code will be read hundreds of times and written only a few times. So invest quality time into spelling out names such as fn into firstname. Fight the urge to use cryptic variable names.
Code Comments
Code should have comments however an abundance of comments can be just as bad as too few. Comments should explain why something is done. The code itself already shows what it is done. So commenting on what is done is redundant. Do not use commenting as a substitute for good code. Another way to say that is that if you need to comment code due to its unclarity then maybe you need to rewrite the code to be more clear and remove the comment.
I found this article which is about using natural language in your code to make it more readable. http://jamesgolick.com/2008/1/14/taking-style-tips-from-natural-language
Comments
Post a Comment