T
T
Taras Serevann2016-03-10 17:07:21
PHP
Taras Serevann, 2016-03-10 17:07:21

What is the best code commenting style?

There seems to be nothing on the PSR and on the Internet on this topic.
There are two styles of code commenting:
Line-by-line, with a sequential explanation of all actions
9e8e9d4729994892a9fe4c241bb7150a.png
And more strict, in which first the explanation and then the action.
0835300d51fb4654a47c9b6ae1acb425.png
Which of these styles is better and more correct? And why? Perhaps there are some official recommendations?

Answer the question

In order to leave comments, you need to log in

4 answer(s)
S
Saboteur, 2016-03-10
@Taras_Serevann

Write comments in English. This will make it easier to support the project in the future, including support by non-Russian-speaking programmers.
Do not write comments that explain a line of code. Even a few lines of code are easier to just read, especially if the variable function/method names are well defined.
You need to comment on the entire method or class, in general terms. Separate lines are commented as an exception, or in case of any changes, such as
// special exception, see issue #123191239

D
Dmitry Kovalsky, 2016-03-10
@dmitryKovalskiy

Both methods are crap. Write beautiful and self-documenting code. Use a sane naming method.
And for such sheets of comments should be punished

R
res2001, 2016-03-10
@res2001

In general, the code comments itself for a person who understands it. And others and comments will not help.
Comments are required only in "subtle", not obvious moments.
For greater readability, give variables and procedures meaningful names.

K
kalyabus, 2016-03-10
@kalyabus

Forget about crooked pens, crutches and other heresy in the comments, they should be more official. Well, commenting on every line is clearly unnecessary, it's like saying out loud "But right now I'll take a step, then another step, then a third and I'll get to the refrigerator, but if on the third step I have a cat, then I'll stumble about her"

Didn't find what you were looking for?

Ask your question

Ask a Question

731 491 924 answers to any question