First let's differentiate documentation and comment. They are different things with different goals.

And let's make it clear that each team knows what is best for them in each project. There are just a few recommendations, experiences that usually work out.

Documentation

API documentation, ie classes, public methods, it is very interesting to document, after all someone will consume them at some point. It may be you who created it years later will use it and not remember how to do it. Better to have documentation within an established pattern than having to read the code to know how to use it.

Although this is custom with the code, it is not part of the code itself. It's good to be around to make any changes easier when the code changes. Although code changes should not force changes to the documentation. But this is another matter.

There is controversy whether to formally document private methods. Most programmers consider that a simple comment is enough, or even nothing, when the method is self-descriptive and has nothing really useful to add anything.

Architecture documentation is also critical for anyone to understand how everything works. Normally it is completely separated from the code. These are explanatory texts and diagrams.

Testing

Tests can be used as an alternative documentation form. But they do not replace a common text. They work more like a technical documentation showing how the components should respond. Instead of saying that a method should always return a positive number, you do a test that checks if this is being done correctly. Some languages have contracts that allow this in the code itself.

Comments

Comments should be used especially when the code can not express what is happening or does something that is not very intuitive. Comments serve to explain why is doing that.

Comments saying what is doing is ridiculous and really only helps novices better understand what is happening, serve to learn. These are didactic comments that should not be used in production codes.

At most times when we see comments saying what the line does, it's redundant.

• Is it confusing?

  Make it simpler.

• Does not make clear what it is?

  Give better names.

• Are you highlighting the block?

  Break into smaller methods.

I've given a deeper answer on this .

Tips for learning to document

See how good projects do the documentation and get inspired by them.

Today's tools to help you format documentation already give you tips on what it should contain. But remember to not talk about truisms, and do not forget important information, especially when it can cause unexpected problems or behavior.

What would be a good way to document the software?

It depends on several things, but I would say that initially it would be following the design pattern that the community that developed the standard recommends.

For example, in Java we have Javadoc . In .NET we have XML Documentation . In Python we have a good practice guide , and so on.

Soon thereafter, it could be some standard documentation that is inherent to the team that develops. When there is no team that develops, it may be some pattern followed by the community in which the code stays. GitHub, for example, has a habit of documenting Markdown .

Is it interesting to put documentation in the code?

Always is. What should be avoided is codeiness in the code. I personally have the following premises:

• Do not document obvious snippets (truism is subjective, so document what my conscience and common sense say is a good idea);
• Use variable names that indicate what it does, without contractions. Variable name constraints create ambiguities;
• Write something that the programmer will save time, not lose: I know the expression is not for everyone. There are great programmers with limited ability to express themselves, and they can write comments that they are most troubling to help. That is, if the comment left does not help, better remove it.

Is it useful only for inexperienced developers early in their careers or also for experienced developers who already have mastery in language?

For everyone, I would say. Especially for the juniors. Considering that most of the universe of programmers is junior, I would say that it is very much aimed at them.

Also useful for seasoned programmers. It does not mean that a programmer with a high degree of seniority will read the whole code and understand everything.

Are there criteria for such?

This is a bit subjective. I go by the golden rule: Is information useful? Document.