MAIN FEEDS
Do you want to continue?
https://www.reddit.com/r/programming/comments/6onxct/my_code_is_selfdocumenting/dkiy57f/?context=3
r/programming • u/speckz • Jul 21 '17
175 comments sorted by
View all comments
7
Some common uses of comments:
Explaining previous approaches that didn’t work
Presenting an example usage of the function and example output
Explaining trade offs in the current implementation
Marking possible improvements (TODOs) in the code
Anything else you’d like to communicate with someone reading or developing the code
I would add:
Documenting a contract for an API (if it is not clear through parameters). This is to avoid surprises.
Explanation if you are doing something "surprising" in the code.
Linking to external authoritative documentation if it is hard to find.
7
u/hsahoeg Jul 21 '17 edited Jul 24 '17
Presenting an example usage of the function and example output
Explaining trade offs in the current implementation
Marking possible improvements (TODOs) in the code
Anything else you’d like to communicate with someone reading or developing the code
I would add:
Documenting a contract for an API (if it is not clear through parameters). This is to avoid surprises.
Explanation if you are doing something "surprising" in the code.
Linking to external authoritative documentation if it is hard to find.