What is the appropriate level of detail for notes?

Question

When I register the code, I once write very long, detailed notes about the verification, in other cases I write very short (or do not notice at all). Longer notes include information on why the change was made (business reasons, customer interactions, etc.). However, I am not sure if posting notes are the right place for such details. Most of the notes that I saw are usually short and simply refer to an error.

What is the appropriate level of detail for notes?

Answer 1

The correct answer, I found, depends on the needs of your organization. This sounds vague, but the main reason to provide details for code verification is context and understanding if this registration needs to be revised or revised. It can be incredibly verbose, or it can be surprisingly simple.

At one company, our code checks will refer to the number # + ticket. This is compared with our SVN with respect to the Trac ticket number, which indicated all our data on this problem or function that we used. We referenced everything through Trac, so saving our data in this form worked best for us.

For you, it depends on how you and your team work. I would use the information that you store in your notes about the need for data, how often they are referenced, and what happens if you lose context (i.e., you don’t know why the change was made).

Another consideration might concern these notes outside your code repository, which may not be the most efficient mechanism for storing this information. However, I consider this a personal preference.

Answer 2

No matter what your manager or company documentation says;)

In short, better. This is not the right tool for lengthy documentation - for this, your software for tracking errors / signs has been created, and in most cases it can integrate with your original control.

Answer 3

It’s enough when you learn about what happened a few weeks after the magazine.

I use these logs to check what was done on the last day (or days) in the project that I am heading.

Shorter messages are not needed, which means better. More posts. Just keep in mind the purpose of these comments: to give an overview of activity in the version control system.

Answer 4

In my experience with version control, I tend to curse those that didn't leave a note at all, or a note that takes 5 minutes to dig up.

If you use your version control system to look at the history of a file to find a specific change, it is best to include a short comment about why and what. How to do this in the source code documentation.

Answer 5

Whenever I write a comment or a commit log message, I ask myself: “What should the next guy know, what can they ask me about?”

The answer to the question seems to be an easy way to keep comments concise and helpful. It also avoids antidocumentation (paraphrasing code, often unintentionally ironically) or paraphrasing metadata that vcs will track anyway (added foo.java, time change, new tag "bar-1-1-4")