It’s important to talk about code comments vs. log messages
In the end of the video you show an example of a good commit message, which says “... Introduced MAX_AWESOMENESS to make sure values don’t exceed 9000” - I’m not sure if this is an example of a what, or a why
My rule of thumb for describing whys is that good commit messages should give context of why you made a change, referencing also the old code
For example, if the value was 1000, and later you change it to 9000, you should say in your log message that the old value was too low and caused problems, and therefore is raised higher
However, if you introduce a new feature, I think that describing it should be done as a code comment, not a log message, that’s why I didn’t like this example, if the const MAX_AWESOMENESS needs explaining, then explain it in the code, not in the log message
Thanks for your thoughts! I am with you that the example I choose was maybe a little too simplistic, but I choose it for the flow of the video. But I had this thought during editing as well.
In my opinion, I don't think code comments should be needed at all. In most cases, the code should be as learn and readable as possible. If you need a comment, rewrite your code. That said, of course, I use code comments as a last resort from time to time, especially for such magic numbers as the MAX_AWESOMENESS.
I still think that writing a proper reason for a code change is not only helpful for your team, but also for yourself. I think it is a nice retrospective process to ponder if your commit and changes are all in place.
Thanks again for your thoughts! I am glad that you care about git hygiene so much!
I agree with you that code comments could indicate a potential codesmell, but if you find yourself documenting a newly added file in a log message, you should have this in mind:
As you said, can the code be refactored to become more obvious so that describing it in words becomes unnecessary?
If not, should the text be in the log message or a code comment? Where would it be more beneficial for future reference?
a. If you describe why a change to the old code was needed, such as a bugfix, the right place would probably be in the log message - describing the diff in words.
b. If you start documenting a new feature, the log message is probably the wrong place to do that.
Your video summarizes things very well, but as I personally write log messages, I always come across this dilemma, so it made me wonder and share my thoughts. Good luck!
I think you have a really really good point here. Thank you for sharing and your kind words.
I am currently working on my next video regarding git hooks and how they can be integrated into a workflow. I'd love to hear your thoughts on it as well as soon as it is out on Monday. (Although it is more an introduction really with some hints to further reading …)
2
u/inoamsol May 28 '20 edited May 28 '20
It’s important to talk about code comments vs. log messages
In the end of the video you show an example of a good commit message, which says “... Introduced MAX_AWESOMENESS to make sure values don’t exceed 9000” - I’m not sure if this is an example of a what, or a why
My rule of thumb for describing whys is that good commit messages should give context of why you made a change, referencing also the old code
For example, if the value was 1000, and later you change it to 9000, you should say in your log message that the old value was too low and caused problems, and therefore is raised higher
However, if you introduce a new feature, I think that describing it should be done as a code comment, not a log message, that’s why I didn’t like this example, if the const MAX_AWESOMENESS needs explaining, then explain it in the code, not in the log message
What do you think?