Answer the question
In order to leave comments, you need to log in
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
And more strict, in which first the explanation and then the action.
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
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
Both methods are crap. Write beautiful and self-documenting code. Use a sane naming method.
And for such sheets of comments should be punished
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.
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 questionAsk a Question
731 491 924 answers to any question