From 44fea3ce7c4f9670847ae389c8d74defca525f46 Mon Sep 17 00:00:00 2001 From: Oliver Davies Date: Sat, 7 Oct 2023 01:12:35 +0100 Subject: [PATCH] daily-email: add 2023-10-02 Only comment what needs to be commented --- src/content/daily-email/2023-10-02.md | 37 +++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 src/content/daily-email/2023-10-02.md diff --git a/src/content/daily-email/2023-10-02.md b/src/content/daily-email/2023-10-02.md new file mode 100644 index 000000000..563817180 --- /dev/null +++ b/src/content/daily-email/2023-10-02.md @@ -0,0 +1,37 @@ +--- +title: > + Only comment what needs to be commented +pubDate: 2023-10-02 +permalink: > + archive/2023/10/02/only-comment-what-needs-to-be-commented +tags: + - software-development + - clean-code +--- + +"If you comment everything, people won't read them." + +"As soon as one comment is incorrect, the result will be ignored." + +These are two comments I heard recently referring to code comments. + +If there are too many comments, people will get lost in the information. They won't be able to differentiate boilerplate comments from valuable ones, and as soon as one comment is incorrect, people will assume that others could likely be incorrect too and ignore them. + +A solution to these is to only comment what needs to be commented. + +Only write comments that add value, and if there are fewer comments, they are easier to read and maintain - making it more likely they will be incorrect. + +This is an example from an open source pull request: + +```php +/** + * An interface for field access override. + */ +interface FieldAccessOverrideInterface { +``` + +In my opinion, this doesn't add any value or additional context as it repeats what's already there. + +Something I put in my project configuration files is to tweak the coding standards to not check, for example, for class and method docblocks - allowing me to add them where I want and where I think they're needed and add value. + +I think this is better than having comments everywhere, and I can focus on the ones that matter.