Everyone knows that the commented code, especially when using a versioning system, is anti-pattern (a code with a dandy).

Do I need to transfer this rule to the template language code ( Smarty , Twig , etc.)?

Moreover: are commenting blocks preferable to deleting them?

  • Comments are written primarily for themselves. If this somehow facilitates the task, then why not? Write, do not hesitate! - Sergey
  • Всем известно, что закомментированный код, особенно при условии использования системы версионирования is unknown to me. Where does this come from? Here I have a billion-line code. Am I supposed to remember what is displayed there and for what rummaging in the versions? Brad is the same. - Alexey Shimansky
  • Well, I realized that the Russians did not know about it. Severe American engineers respond to you: softwareengineering.stackexchange.com/a/190222/74973 - hellboy
  • In addition, in my previous work, the consultant criticized me for the commented commented code. - hellboy pm
  • OK, and now attention to the question: what kind of comments should or should even be used when commenting on “code” in templates a la Smarty - hellboy

1 answer 1

Commented code is considered antipattern. It's my personal opinion. The code should work, why shouldn't it be in the comments.


Further I express the generally accepted point of view, without the relativity of a language (Smarty, Twig, etc.)


Bad comments

The code needs comments.

I'll start right away with almost no comments.

There should be a minimum of comments that answer the question “what happens in the code?

Interestingly, in the code of novice developers, there are usually no comments, or they are just of this type: “what is done in these lines”.

Seriously, good code is clear.

R. Martin remarkably expressed this in his book “Clean Code” : “If it seems to you that you need to add a comment to improve understanding, it means that your code is not simple enough, and maybe you should rewrite it”.

If you have formed a long “sheet”, then it may be worth splitting it into separate functions, and then from their names it will be clear what this or that fragment does.

Yes, of course, there are complex algorithms, tricky solutions for optimization, so you can’t just ban such comments. But before you write like this - think: “Is it possible to make the code clear without them?”


Good comments

And what comments are helpful and welcome?

  • The architectural commentary is “how it is, in general, arranged.”

    What components are there, what technologies are used, interaction flow. What and why this script. A bird's-eye view. These comments are especially needed if you are not one, but a big project.

  • Reference comment before the function - about what exactly it does, what parameters it takes and what it returns.

There is a JSDoc syntax for such comments.

 /** * Возвращает x в степени n, только для натуральных n * * @param {number} x Число для возведения в степень. * @param {number} n Показатель степени, натуральное число. * @return {number} x в степени n. */ function pow(x, n) { ... }

Such comments allow you to immediately understand what the function accepts and does, without delving into the code.

By the way, they are automatically processed by many editors, such as Aptana and the editors from JetBrains, who take them into account when autocompleting and also output them in auto-prompts when typing code.

In addition, there are tools, such as JSDoc 3, that can generate HTML-based documentation from such comments. More information about this can also be found at http://usejsdoc.org/ .

... But much more important may be comments that explain not what, and why exactly this happens in the code!

As a rule, it is possible to understand from the code what it does. Of course, everything happens, but in the end, you see this code. However, much more important may be what you do not see!

Why is this done that way? To this the response code itself does not give.

For example:

There are several ways to solve the problem. Why was this one chosen?

For example, you tried to solve the problem differently, but it did not work out - write about it. Why did you choose this particular solution? This is especially important in cases when not the first method that comes to mind, but some other one is used.

Without this, for example, this situation is possible:

  • You open the code that was written some time ago, and you see that it is “non-optimal”.

  • You think: "What a fool I was," and rewrite under the "more obvious and correct" option.

  • ... The rush, of course, is good, but only this option you have already thought about before. And they refused, and why - they forgot. In the process of rewriting, they remembered, of course (fortunately), but the result was a loss of time to re-think.

Comments that explain the choice of solution are very important. They help to understand what is happening and take the right steps in developing the code.

What non-obvious features does this code provide? Where else are they used?

In a good code should be at least obscure. But where it is - please comment.

Comments are important. One of the indicators of a good developer is the quality of comments, which allow you to effectively maintain the code, return to it after any pause, and easily make changes.