Is there a correct way to comment on a code snippet?

Question

Is there a correct way to comment on a code snippet? For example:

// Esconde a tela
this.Hide()

or would be:

this.Hide()
// Esconde a tela

or even:

this.Hide() // Esconde a tela

Is there some kind of convention for such?

Answer 1

I can’t imagine a case where a comment underneath the fact is useful.

It is obvious that comments on the same line can only be made if the text is too short.

When you learn when you comment you realize that the comment in production code is rarely useful if it is put in the same line. There’s no room to explain why that is. And Mum prototype, exercise, something didactic is different.

So putting it right up is usually more appropriate. This is reinforced in C# by Microsoft Convention Guide, posted in comment above stderr. Not even they follow it always. Good programmers always understand the context and know when to use a convention and when to avoid it.

Note that you need to analyze other conventions as well. There are those who determine a maximum length for the lines. Others do not impose this limit and let the line break solve it.

When commenting on the line itself it is known that it refers to that line. When commenting above it is not certain how far the comment goes. As the comments need to explain something broader, it is common to be more interesting to put just before what will be explained.

Of course you can have your own convention. The important thing is to be consistent.

But we are talking about fixed comments. It is not the same thing as a quick comment, the so-called comment out, that one does to try something without a part of the code (something that should really be something quite temporary). Temporary comments depends a lot on the need. It is common to use more /* ... */. But a // to eliminate the end of the line, possibly putting another part in place may be the simplest to do. The fact that if you’re not going to survive, and you really can’t, it doesn’t really matter much, it gets very personal.

Not comment on

But the ideal in this case is not to comment. The example is not good. In another context it could be that some special reason better defined the choice.

The commented code is obvious, at least in the general context of development.

Comment should always say why it was done and not what was done. And you should only say why if you have a good reason. If you’re going to say what’s been done, fix the code to be readable on it.

Comments are out of step with the code. It is common for the programmer to change the code and forget to change the comment. In a way it violates the DRY code. And they encourage people to write less readable codes.

Of course, in didactic codes, a commentary saying what you’re doing makes some sense, but it would have to be very explanatory. Not simply repeating the code. In this case it may be that the comment *inline* be more appropriate.

I won’t go into detail, there are already questions about it:

• Code comments when working in a group
• How to know the right measure of comments?
• Wikipedia

Answer 2

The specification of the language C# does not define a coding standard. However, guidelines are used by Microsoft to develop samples and documentation.

Coding conventions meet the following purposes:

• Create a consistent look for code, so readers can focus on content and not layout.

• Allow readers to understand the code faster, making assumptions based on previous experience.

• Facilitate the copying, modification and maintenance of the code.

• Demonstrate C Recommended Practices#.

Commentary:

• Place the comment on a separate line, not at the end of a line of code.

• Start the text of the comment with a capital letter.

• End the text of the comment with a period.

• Enter a space between the comment delimiter (//) and the comment text.

• Do not create formatted asterisk blocks around comments.

Example:

// The following declaration creates a query. It does not run
// the query.

Reference: Coding conventions in C#