Comments: Difference between revisions
From YM2149.org
Jump to navigationJump to search
(Created page with "* comments distract from the code and are too easily lost in conflict resolution, or moved in reformatting ** the initiated do not need to re-read the comments * use self-documenting names in preference to comments, add a new function if necessary ** this is of more use to the uninitiated * when working on a ticket, that can be the decision record and commit messages should already refer to it * the readme doesn't have to be behind a pull request wall, it can simply cont...") |
No edit summary |
||
| Line 6: | Line 6: | ||
* the readme doesn't have to be behind a pull request wall, it can simply contain a link to the wiki to make documentation more inclusive | * the readme doesn't have to be behind a pull request wall, it can simply contain a link to the wiki to make documentation more inclusive | ||
* when working on legacy code, assume it's all there for a reason even if it's bad code | * when working on legacy code, assume it's all there for a reason even if it's bad code | ||
** effectively this is [https://en.wiktionary.org/wiki/Chesterton%27s_fence Chesterton's fence] when the original motivation has been lost | |||
[[Category:Programming]] | [[Category:Programming]] | ||
Revision as of 18:04, 12 November 2024
- comments distract from the code and are too easily lost in conflict resolution, or moved in reformatting
- the initiated do not need to re-read the comments
- use self-documenting names in preference to comments, add a new function if necessary
- this is of more use to the uninitiated
- when working on a ticket, that can be the decision record and commit messages should already refer to it
- the readme doesn't have to be behind a pull request wall, it can simply contain a link to the wiki to make documentation more inclusive
- when working on legacy code, assume it's all there for a reason even if it's bad code
- effectively this is Chesterton's fence when the original motivation has been lost
