Documentation in software development

Question

I would like to ask my question on the basis of in that matter on tests.

There are different ways to document a software, the ones I’ve noticed the most are:

• Class documentation (developer comments on the objective and/or task of that class)
• Method documentation (developer comments on the objective, actions and/or tasks that method performs)
• Documentation within the code (the developer comments on what happens on a particular line of code)
• Documentation generated in an automated manner from the Javadocs, for example.

Therefore, basing on some questions from the link I mentioned above:

• What would be a good way to document the software?
• Is it interesting to put documentation in the code? Is it useful only for inexperienced developers at the beginning of their career or also for experienced developers who already have mastery of the language? I ask this because I have heard that they do not need documentation because reading the code you already know what action that piece of code performs. But from what I observe the architecture of the system has its influence, the way the developer developed it, I can cite example the concept of MVC, Dependency Injection that have their architectures, so the developer could create a different architecture for a design pattern within the application.
• There are criteria for this?
• As a basis for the best response from question that I mentioned about testing, within the system documentation there are descriptions, such as, Integration test, Unitary Test, Canary Release what were mentioned in the answer? But in that question I created referring to documentation.

Answer 1

First let’s differentiate documentation and commentary. They are distinct things with different objectives and so we treat differently.

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

Documentation

API documentation, that is, public classes and members, it is very interesting to document, after all someone will consume them at some point. You may be the one who created it, years later you’ll use it and not remember how to do it. Better to have documentation within an established standard than to have to read the code to learn how to use it.

Although this is usually next to the code, it is not part of the code itself. It is good to be close to facilitate any change when the code changes. Although code changes should not force changes in documentation. But this is another subject.

There are controversies 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 that adds something.

Architectural documentation is also critical for anyone to understand how everything works. It is usually completely separated from the code. It is broadly explanatory text and diagrams.

Testing

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

Commentary

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

Comments saying what is making themselves look ridiculous and really only serve to help beginners understand better what is happening, serve to learn. These are didactic comments that should not be used in codes in production.

Most of the time when we see comments saying what the line does, it’s redundant.

• Is confused?

  Make it simpler.

• It doesn’t make clear what that is?

  Give better names.

• Is highlighting the block?

  Separate into smaller methods.

I gave a deeper answer on this.

Tips for learning to document

Look to see how good projects do the documentation and get inspired in them.

Existing tools today to help format documentation already give hints of what it should contain. But remember not to mention Rights, and not to forget important information, especially when it can cause problems or unexpected behaviors.

Answer 2

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 pattern recommends.

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

Soon afterwards, it could be some standard of 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 gets. Github, for example, has as a habit the documentations involving the Markdown.

It is interesting to put documentation in the code?

It always is. What should be avoided is prolixity in the code. Personally, I have the following premises:

• Do not document obvious excerpts (obviousness is subjective, so document what my conscience and my common sense say is a good idea);
• Use variable names that indicate what it does without contractions. Variable name contractions create ambiguities;
• Write something that the programmer saves time, not loses: I know what expression is not for everyone. There are great programmers with a limited ability to express themselves, and who can write comments that are more disturbing than helping. That is, if the comment left does not help, better withdraw it.

It is only useful for inexperienced developers at the beginning of their career or for experienced developers who already have mastery in the language?

For everyone, I would say. Especially for the juniors. Considering that most of the programmer universe is junior, I’d say it’s pretty much geared towards them.

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

There are criteria for this?

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