Feed
I've observed that at times comments are written but not updated as the requirements change. Can't agree more. Ruben you've very well highlighted different use-cases and expectations from a dev.
I write a lot of custom code and always breathe a sigh of relief when my comments help me make the changes my clients request. Updating the comments is an absolute must.
My files contain a short version history summarizing the changes, making it easier to locate the specific segment of code.
Great examples and well written. Thank you for sharing!
Problems can be avoided by making these hidden connections between code visible using comments.
While the statement is correct it highlights a problem that I think it requires more attention. What you call "hidden connections" can be described as "cognitive load" and in this case, the need of having to add a comment to make it "safer" signals that the interface has not been properly designed (the Kafka interface that exposes those keys to be modified).
Comments are our last line of defence against poorly defined dependency interfaces.
Excellent article! Indeed, commenting is neglected sometimes, but it could turn out to be time-saving and, later on, money-saving. I like this revelation:
"Good programmers write good comments as well. Poorly commented code behaves as technical debt."
Thanks for sharing!
I always appreciate good comments on a fairy lengthy function. Sometimes no matter what you do something is going to look a little complicated.
Help out your fellow develops and add some comments.
Excellent writing, thank you for the insights Ruben Scheedler! 👏👏
Thank you for sharing ❤
I am trying hard to not comment on my code because I believe if I named the variables, the methods and the classes right, everyone will understand it.
But this article changed my mind about using my comment to give context to the future devs that will maintain the code. I am going to comment when I can't fix a technical debt or when I create technical debt.
Very nice article. I think your point on commenting why and not what is very insightful
Tanish Shrivastava
Thoughts, Tutorials, reviews.
I remember I had a discussion with one guy once, who said that if you want to understand your thought process a few months later, you should write that on the top of your code in multiline comments.
I haven't worked in the professional environment yet, so I'm not sure that this advice would be useful there. But for now in my learning process as I create new things, It has helped me a lot, since I don't have to figure out what I was thinking all those months ago just by reading the code.
Thanks for this wonderful article, Ruben Scheedler.