Difference between revisions of "Commenting"
(initial thoughts) |
(do not repeat Haskell report) |
||
Line 5: | Line 5: | ||
In the first place you should write as clearly as possible |
In the first place you should write as clearly as possible |
||
such that comments are not necessary. |
such that comments are not necessary. |
||
+ | Comments cannot be checked by the compiler |
||
+ | and thus they tend to diverge from actual implementation. |
||
If you are going to write a comment, |
If you are going to write a comment, |
||
− | think about the following before you actually write it: |
+ | think about the following items before you actually write it: |
* Is it a comment that documents unexpected behaviour? Then better avoid the unexpected behaviour. Example: |
* Is it a comment that documents unexpected behaviour? Then better avoid the unexpected behaviour. Example: |
||
Line 15: | Line 17: | ||
then better do not define a <hask>Num</hask> instance for it. |
then better do not define a <hask>Num</hask> instance for it. |
||
(Sure, <hask>Float</hask> types are not ideal.) |
(Sure, <hask>Float</hask> types are not ideal.) |
||
+ | I repeat: Try hard - very hard - preferably repeatedly - to remove unexpected behaviour from your program. |
||
+ | Comments can never fix unexpected behaviour. |
||
− | * Is it an obvious |
+ | * Is it an obvious comment? Example: |
<haskell> |
<haskell> |
||
-- swap the elements of a pair |
-- swap the elements of a pair |
||
Line 26: | Line 30: | ||
* Does the comment duplicate the Haskell report? |
* Does the comment duplicate the Haskell report? |
||
+ | <haskell> |
||
+ | let b=a+1 -- add one to 'a' |
||
+ | </haskell> |
||
+ | The meaning of <hask>+</hask> and <hask>1</hask> should be clear from the Haskell report. |
||
+ | You may better comment the intention of your code like in |
||
+ | <haskell> |
||
+ | let b=a+1 -- increase the loop counter 'a' |
||
+ | </haskell> |
||
+ | But again, writing programs that do not require comments are the better choice. |
||
+ | E.g. |
||
+ | <haskell> |
||
+ | let newCounter = oldCounter+1 |
||
+ | </haskell> |
||
Revision as of 11:37, 30 December 2010
It is generally a good idea to write comprehensible programs, and adding comments to your program can help to achieve that goal. However it is not true that every program can be become comprehensible by adding enough comments. In the first place you should write as clearly as possible such that comments are not necessary. Comments cannot be checked by the compiler and thus they tend to diverge from actual implementation. If you are going to write a comment, think about the following items before you actually write it:
- Is it a comment that documents unexpected behaviour? Then better avoid the unexpected behaviour. Example:
a+b-b -- you cannot delete (b-b) because the operations are not associative
If the operations are not associative for your custom type,
then better do not define a Num
instance for it.
(Sure, Float
types are not ideal.)
I repeat: Try hard - very hard - preferably repeatedly - to remove unexpected behaviour from your program.
Comments can never fix unexpected behaviour.
- Is it an obvious comment? Example:
-- swap the elements of a pair
swap :: (a,b) -> (b,a)
Congratulations: You have chosen a function name and a type signature that make the purpose of the function pretty without any comment. Thus: omit the comment, you only risk that it becomes out of sync with the function.
- Does the comment duplicate the Haskell report?
let b=a+1 -- add one to 'a'
The meaning of +
and 1
should be clear from the Haskell report.
You may better comment the intention of your code like in
let b=a+1 -- increase the loop counter 'a'
But again, writing programs that do not require comments are the better choice. E.g.
let newCounter = oldCounter+1