DON'T write comments in your code!

preview_player
Показать описание
Should a Software Engineer write comments? It may seem like an easy yes since comments are much easier to read than code, but it is surprisingly more complicated than that. I just want to explain why I almost never write comments and why you shouldn't write comments in your code, too!
Комментарии
Автор

The quick changing background is distracting and should come with an epilepsy warning.

Sauron...
Автор

well said i get complements for making easy to read code that is logical and simple. i spend 50% of my coding time thinking not typing

EFFbriskethead
Автор

In my opinion, splitting everything up into tiny functions can lead to the code being more messy than it was then it was all in one function.
When it is spit up you may have to jump around to see what it does (sometimes you can guess from the name, but other times it's not that easy).
When it is in one function you can just look downwards in the function to see what it does. and you can divide the parts of the function up using white space, comments, and code blocks so that it is easier to see which part is which.

mrt_
Автор

jsDoc, GoDoc and Rustdoc are standard for libraries and SDKs. There is no way to write a code that is expected to live for long without some docs.

Alex-hrdf
Автор

Comments can be really useful if you want to signal that you plan on making it better, fixing some edge case, etc, or just a note about something that may not be obvious.
In those cases I think it's fine. Also, I write comments like this:
// @NOTE: some note
// @TODO: some todo
and I have a program I made myself to extract those comments so I can see where they are.

mrt_
Автор

btw, documentation can also lie. and in my experience can be less updated than the comments in the code.

mrt_
Автор

I don't agree with most of whats said in this video.

For your "processSalesData" example, you present the solution of splitting up the code into many tiny functions with 1-4 lines each. With this approach, comments indeed become unncessary as every function does so little that the function name essentially acts as a comment. However, you have also significantly increased the LoC and obfuscated the control flow, both of which make reading the program a lot harder imo. It also makes large refactors a massive pain because you have to change a million different functions.

Of course comments are never a replacement for clean code. But cleanliness isn't the only factor to consider when writing code. You also need to balance performance and development time, among other things.

Then, you suggest that instead of writing comments, you should put the information in the documentation of the function instead. I don't understand this point tbh, these are two very different things. The documentation of a function is user-facing, it is meant to explain how this API should be used. Comments within the functions are only for the developers the library/tool in question and they explain how the code actually works under the hood. These are not the same and one does not replace the other.

Moving on, you note that unit tests can somehow (?) replace comments. Again, this is confusing documentation of the function as a whole with comments describing how individual parts of said function work. Unit tests can only act as a reference for how a piece of code should be used, they're not a replacement for comments.

alaska