The BEST Code Comments | Code Walks 021

The best code comments are the unwritten code comments. If you are commenting your code, that implies that your code is difficult to understand without them. The solution is not code comments, the solution is to refactor your code.

GEAR USED

[gigajoules]

I can't remember where I heard it but someone once said 'A comment is a lie waiting to happen.'
A lot of the time devs will change code and fail to update comments, leading to even more confusion in the long run when the comments contradict already confusing code.

[wobblyrampack]

This is a really interesting topic. I am coming around to your way of thinking - comments should be almost totally unnecessary! I am reading Martin Fowler's refactoring book and he makes an interesting point: Whenever he feels the need to comment a section of code, instead he extracts that bit of code as a separate method. And he names the new method so that no comment is needed.

[davidackling-jones]

Just wanted to add a comment...
thanks for another interesting video. Please keep making them Chris.

[whattehfix]

Uncle Bob point of view, just true :)

[PolovII]

Can you make a video reacting to the most weird and funny code comments ever made? Would be fun

[chrisjust]

I disagree (mostly). You're right that we should try to give functions & variables obvious names to increase readability and reduce the need for comments, but for certain complicated pieces of logic that took you a while to figure out and could easily be misinterpreted by other people, adding a comment will save them (and you in the future) a lot of time by not having to reverse engineer what that code is doing.
You also have to remember that not everyone on your team is going to be at the same experience level as you and they might inadvertently change your code in a way that breaks it because they didn't know there was a very specific reason why you had a line of code in a certain place.
Lastly, since I'm a QA Dev, I depend on documentation to tell me exactly what the requirements of a feature are; so I add function documentation for ALL of my functions and I wish the regular developers had better (or at least some) documentation to make my life easier. The other benefit of adding function documentation is that Visual Studio can then show the documentation with intellisense when you hover over a function.

[AlesisManzano]

Unbelievable that some people uses code like as a binnacle haha