Senior Wisdom
Senior Wisdom
13 comments
-
my comments are my fav reading material
-
comment anything that needs extra info to explain what and why (if the code is not inherently self explainable)
-
And depending on your audience or how often you (don't) go back and review it, it can help to comment the things that are self explanatory.
I write a lot of scripts for my team and have to make them "maintainable" by the people in my department (who are as familiar with the concept, as your buddy that calls the gym the James), so I will regularly over comment so that any ape can come along and hopefully know what the script does.
-
Works great in theory, but then people inevitably forget to update the comments and code gets out of sync with what the comment says. At which point you're in even worse situation than not having any comments at all.
-
-
comment the code! tell future you why is that needed and what its doing.
-
Write better code, with good names and sensible interfaces. Comments can get bugs just like code, but it doesn't have a compiler or unit tests, so only code review keeps it aligned.
-
-
Write an ungodly large amount of code-comments - up to a point where you add 20 lines of explanations to a 6 lines long function where two lines are variables assignments.
Source code is for humans to read. The compiler ignores the comments.
-
Somebody has to maintain the ungodly large amount of comments as the code gets updated over time, and if people screw that up then the comments become less than useless.
-
That's the downside, yes.
-
-
13 comments