How do you write comments in the code, how do you highlight program blocks with comments?

Question

PHP

I decided to ask such a slightly unusual question.
I have long developed a system for writing comments in code (be it a php program or just html layout), and we are talking about highlighting various blocks with comments.
For example, if ( ) { opens, and after about a hundred code terms, it closes.
I usually do this:

// проверка переменной на равенство 0 -------------
if ($x==0) {
   ...
}
//  / проверка переменной на равенство 0 -------------

Those. at the beginning of the block (condition, loop, etc., or just some block of code that needs to be highlighted) I write
a comment (for example, the name of the block or a description of what is done in it) and at the end of the block (after closing the curly brace ) the same comment, but with a backslash, which indicates that the block ends here.
I wanted to find out from the community who else uses what techniques for a similar task. Maybe there is some more convenient scheme.

Answer 1

and somewhere after a hundred code period, it closes.

That is a clear candidate for refactoring.
Allocate the whole hundred lines to a function with an explicit short description in the name of what it does.

Answer 2

I use the following block selection. Asterisks for individual modules, hyphens for individual functions. The length of such a string is 80 characters. As a result, the code is clearly separated.

//**************************** Служебные функции *****************************//
//------------- Функция поиска свободного id в массиве  ----------------------//
function GenId() {
   var i = 0;
   while(arr[i]) {i++;}
   return i;
}
//----------------------------------------------------------------------------//
//****************************************************************************//

Answer 3

Here again, everything is thought out before us. All your functions and methods should contain a minimum of code and perform ONLY ONE action. If the method contains more than ~10 lines, it is better to split it into two methods. Such short functions and methods will be clear without comment. We put comments before the method itself so that the automatic documentation system can understand them. For example:

/**
 * Метод делающий то-то
 * @param first первый параметр
 * @param second второй параметр
 * @return возвращаемое значение
 */

Answer 4

The best technique is to write code without commenting. Of course, the code should be understandable :)
I never comment on solid blocks. If necessary, then one line, no more. For example:

if (null == null) {
    // If null == null then we need do this
} else {
    // If not I want something more
}

Answer 5

If you do not write some kind of training code, where you need to chew on each construction, then such comments are generally unnecessary and complicate reading. Often, you will compile the code in your head faster than you can read the comment. A JavaDoc/PHPDoc-style method annotation is enough for a developer. Comments inside a function are justified only for TODO or some tricky magic, which is usually written as the commenter above said.

Answer 6

Judging by your example, you duplicate the code in the comments, this is wrong, the comment should answer the question - why? The programmer will be able to read the code himself, but understand why ...
If we ignore the contents of the example, then in your example there is a problem - duplication, changed in 1 place, forgot in another - and now the comments contradict each other. Use language, not comments, to break code into blocks.

Answer 7

PhpDoc & etc.
Comments in the code only in very non-obvious moments. Good code comments itself

Answer 8

If you are writing a complex method (such things happen), then the book "Perfect Code" advises you to start writing a method with comments in general. Write down with comments what you want to write, then fill in the real code in the right places between the comments. After the end - remove the obvious. Profit.

Answer 9

I write the meaning of the block and not its action
// -----checking for zeros by the variable $var
if($var==0) {
//......
}
an example of a meaningless comment. it is better to describe how the given code is related to the external .
// $var number of entries, displaying similar news
for good visualization, I make comments in the form:
//================= $var number of entries, displaying similar news ===== ========

Answer 10

On large blocks (for example, jQuery or switch I write something like this (of course there are indents, but comments do not harm):

}); // end each()
}); // end bind

or

break; }; // end case
}; // end switch

or
Of course, this may seem redundant :) But during development, my convenience is more important to me than the compiler :)

Answer 11

I write comments about the same as you, but only at the development stage.
In the final, I leave comments in the code only before the beginning of each function or method, if their purpose and parameters are not obvious from the point of view of the code, or if a certain algorithm was used.

Answer 12

phpdoc.org